Expand notebook FileAttachment and table helpers toward Observable System Guide data examples #134

New issue

Closed

opened 2026-05-27 16:05:59 +00:00 by steve · 0 comments

steve commented

2026-05-27 16:05:59 +00:00

Owner

Problem

The current notebook runtime supports lapis.FileAttachment(path) for arrayBuffer, text, json, and blob, but it does not yet cover the more data-oriented helpers shown in the Observable System Guide such as FileAttachment(...).csv() and related attachment-to-table flows. The current runtime also lacks Observable-style Inputs.table(...) parity for those examples.

Goal

Add the next attachment and table helper slice that makes the markdown-native notebook runtime friendlier for System Guide-style data examples while preserving notebook-owned table rendering and vault-relative file access rules.

Scope

Add data-oriented lapis.FileAttachment helpers for structured tabular data, starting with csv() and tsv().
Define how typed parsing options map onto the Lapis notebook runtime and its supported CSV loading path.
Decide whether Inputs.table(...), a notebook-owned equivalent, or a documented lapis.table(...) pattern is the supported parity surface for attachment-driven table display.
Extend the markdown-native System Guide fixture or add a sibling fixture to cover attachment-driven tabular examples.
Add focused tests for tabular attachment loading and rendering.

Non-goals

Do not add arbitrary remote file access beyond the current notebook-relative vault attachment rules.
Do not replace the notebook-owned dataframe renderer with a raw Observable table inspector.
Do not broaden this issue into general notebook import or fetch semantics.

Acceptance Criteria

lapis.FileAttachment(path).csv() is supported for notebook-relative attachments.
lapis.FileAttachment(path).tsv() is supported for notebook-relative attachments.
Typed parsing options used by the supported API surface are documented and covered by tests.
Notebook users can render loaded tabular attachment data through the supported notebook table flow without manual JSON conversion in fixture code.
Workspace acceptance covers at least one attachment-driven tabular example derived from the System Guide parity surface.
The notebook parity audit and runtime docs describe the supported attachment and table helper behavior.

Implementation Notes

Reuse the existing notebook-relative attachment normalization rules.
Keep ownership of rendered table behavior in the notebook package, even if compatibility aliases are added.
If Inputs.table(...) remains out of scope, document the supported table-rendering alternative explicitly in the spec.

Suggested Files or Specs To Inspect

packages/notebook/stdlib/src/**
packages/notebook/src/lib/runtime/**
packages/notebook/src/lib/render/dataframe/**
e2e-vault/plugin-notebook/**
spec/src/20-packages/plugins/notebook/documents-and-runtime.md
spec/src/20-packages/plugins/notebook/observable-system-guide-parity.md

Validation Commands

pnpm --filter @lapis-notes/notebook exec vitest run
pnpm --filter @lapis-notes/workspace exec playwright test e2e/notebook-system-guide.spec.ts
make spec-lint
pnpm test:smoke

Follow-up Tasks

Evaluate additional attachment helpers such as image decoding only after tabular loaders are stable.
Revisit whether Observable-style Inputs.table(...) needs a direct compatibility shim or whether the notebook-owned dataframe renderer is sufficient.

Implementation Summary

Duplicate of #131.

Extend notebook data-loading and table-display helpers so the markdown-native System Guide parity surface can cover more of Observable's attachment-driven examples without requiring ad hoc data reshaping in notebook code. ## Problem The current notebook runtime supports `lapis.FileAttachment(path)` for `arrayBuffer`, `text`, `json`, and `blob`, but it does not yet cover the more data-oriented helpers shown in the Observable System Guide such as `FileAttachment(...).csv()` and related attachment-to-table flows. The current runtime also lacks Observable-style `Inputs.table(...)` parity for those examples. ## Goal Add the next attachment and table helper slice that makes the markdown-native notebook runtime friendlier for System Guide-style data examples while preserving notebook-owned table rendering and vault-relative file access rules. ## Scope - Add data-oriented `lapis.FileAttachment` helpers for structured tabular data, starting with `csv()` and `tsv()`. - Define how typed parsing options map onto the Lapis notebook runtime and its supported CSV loading path. - Decide whether `Inputs.table(...)`, a notebook-owned equivalent, or a documented `lapis.table(...)` pattern is the supported parity surface for attachment-driven table display. - Extend the markdown-native System Guide fixture or add a sibling fixture to cover attachment-driven tabular examples. - Add focused tests for tabular attachment loading and rendering. ## Non-goals - Do not add arbitrary remote file access beyond the current notebook-relative vault attachment rules. - Do not replace the notebook-owned dataframe renderer with a raw Observable table inspector. - Do not broaden this issue into general notebook import or fetch semantics. ## Acceptance Criteria - `lapis.FileAttachment(path).csv()` is supported for notebook-relative attachments. - `lapis.FileAttachment(path).tsv()` is supported for notebook-relative attachments. - Typed parsing options used by the supported API surface are documented and covered by tests. - Notebook users can render loaded tabular attachment data through the supported notebook table flow without manual JSON conversion in fixture code. - Workspace acceptance covers at least one attachment-driven tabular example derived from the System Guide parity surface. - The notebook parity audit and runtime docs describe the supported attachment and table helper behavior. ## Implementation Notes - Reuse the existing notebook-relative attachment normalization rules. - Keep ownership of rendered table behavior in the notebook package, even if compatibility aliases are added. - If `Inputs.table(...)` remains out of scope, document the supported table-rendering alternative explicitly in the spec. ## Suggested Files or Specs To Inspect - `packages/notebook/stdlib/src/**` - `packages/notebook/src/lib/runtime/**` - `packages/notebook/src/lib/render/dataframe/**` - `e2e-vault/plugin-notebook/**` - `spec/src/20-packages/plugins/notebook/documents-and-runtime.md` - `spec/src/20-packages/plugins/notebook/observable-system-guide-parity.md` ## Validation Commands ```bash pnpm --filter @lapis-notes/notebook exec vitest run pnpm --filter @lapis-notes/workspace exec playwright test e2e/notebook-system-guide.spec.ts make spec-lint pnpm test:smoke ``` ## Follow-up Tasks - Evaluate additional attachment helpers such as image decoding only after tabular loaders are stable. - Revisit whether Observable-style `Inputs.table(...)` needs a direct compatibility shim or whether the notebook-owned dataframe renderer is sufficient. ## Implementation Summary Duplicate of #131.

steve added this to the Complete Daily-Use App milestone

2026-05-27 16:05:59 +00:00

steve added the

labels

2026-05-27 16:05:59 +00:00

steve

2026-05-29 11:16:02 +00:00