@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/agent-docs/author/components/tables.md

@@ -0,0 +1,64 @@
+---
+id: guide.component.table
+title: Tables
+summary: Add optional filtering and sticky headings to long HTML tables while
+  preserving every row in Markdown.
+type: reference
+area: components
+subarea: components-visuals
+canonical: /author/components/tables
+---
+
+# Tables
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Tables
+
+**Updated: 2026-10-19.**
+
+Ordinary Markdown tables work without a component. For a long table, wrap one table in `<Table>` to add a filter box, sticky column headings, or both in HTML:
+
+```mdx
+<Table filter sticky>
+
+| Name | Environment | Status |
+| --- | --- | --- |
+| Accounts | Production | Enabled |
+| Invoices | Sandbox | Disabled |
+
+</Table>
+```
+
+`filter` and `sticky` are bare boolean attributes. Use either one alone or both. `<Table>` takes exactly one Markdown table and no other content. Its complete table, without controls, appears in the [Markdown twin](https://www.shoalrun.com/author/components/tables.md).
+
+## Try the controls
+
+Filter this table by a name, environment, or status. Several words must all occur in a row; matching ignores case. Press Escape in the filter box to clear it. Scroll inside the table to keep the headings visible.
+
+| Name     | Environment | Status   |
+| -------- | ----------- | -------- |
+| Accounts | Production  | Enabled  |
+| Billing  | Sandbox     | Enabled  |
+| Catalog  | Production  | Disabled |
+| Delivery | Sandbox     | Disabled |
+| Events   | Production  | Enabled  |
+| Files    | Sandbox     | Enabled  |
+| Groups   | Production  | Disabled |
+| History  | Sandbox     | Enabled  |
+| Invoices | Production  | Enabled  |
+| Jobs     | Sandbox     | Disabled |
+| Keys     | Production  | Enabled  |
+| Limits   | Sandbox     | Enabled  |
+| Metrics  | Production  | Disabled |
+| Notes    | Sandbox     | Enabled  |
+| Orders   | Production  | Enabled  |
+| Profiles | Sandbox     | Disabled |
+
+## HTML, Markdown, and agents
+
+The filter needs JavaScript. Without it, the filter field stays hidden and all rows remain visible. Sticky headings use CSS and still work without JavaScript. On narrow screens the table scrolls horizontally. Keyboard users can focus the scrollable table region.
+
+The Markdown twin contains all 16 rows as a regular table. Agents and text-only readers do not need the filter to find a row. Use an ordinary Markdown table when these HTML controls are unnecessary.

package/agent-docs/author/components/tabs.md

@@ -0,0 +1,129 @@
+---
+id: guide.component.tabs
+title: Tabs
+summary: Group alternate views while retaining every view in Markdown.
+type: reference
+area: components
+subarea: components-procedures
+canonical: /author/components/tabs
+---
+
+# Tabs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Tabs
+
+**Updated: 2026-10-26.**
+
+`<Tabs>` presents alternate views, such as two output formats. Use it only when the choices are truly alternatives; a normal heading sequence is easier to read when readers need every section.
+
+## Syntax
+
+```mdx
+<Tabs label="Output format">
+<Tab label="HTML">
+
+The page has navigation and controls.
+
+</Tab>
+<Tab label="Markdown">
+
+The page keeps the content as text.
+
+</Tab>
+</Tabs>
+```
+
+### HTML
+
+The page has navigation and controls.
+
+### Markdown
+
+The page keeps the content as text.
+
+| Element | Attribute     | Meaning                                                                                                                     |
+| ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `Tabs`  | `label`       | Required literal name for the whole group, used by assistive technology.                                                    |
+| `Tabs`  | `equalHeight` | Optional bare attribute. Keeps the group as tall as its tallest tab. See [Keep the height steady](#keep-the-height-steady). |
+| `Tabs`  | `sync`        | Optional group name for matching selections across tab groups on this page.                                                 |
+| `Tab`   | `value`       | Optional matching key; defaults to the tab label. Values must be unique within a group.                                     |
+| `Tab`   | `label`       | Required nonempty literal name for its control and Markdown heading.                                                        |
+
+Use at least two nonempty, direct `Tab` children. A `Tab` cannot stand alone. Other direct children and attributes fail the build.
+
+## Keep the height steady
+
+By default, the group is as tall as its selected tab. When a reader switches between a short tab and a long one, the page jumps. Add `equalHeight` to size the group to its tallest tab instead. The content below the group stays put.
+
+```mdx
+<Tabs label="Output format" equalHeight>
+```
+
+The setting changes the HTML only. Without JavaScript, all panels stay visible. The Markdown twin is the same with or without it. Use it when your tabs differ in length. If one tab is much longer than the rest, leave it off, because every shorter tab then shows blank space.
+
+## Synchronize related examples
+
+Give related groups the same `sync` name. Choosing a tab updates other groups with a matching `value`, or a matching label when no value is supplied. Matching is case-sensitive. A group without that choice keeps its current selection; groups without `sync` stay independent.
+
+```mdx
+<Tabs label="Install a client" sync="language">
+<Tab label="JavaScript" value="js">
+npm install example-client
+</Tab>
+<Tab label="Python" value="py">
+pip install example-client
+</Tab>
+</Tabs>
+```
+
+These two examples share a selection. Try choosing Python in either group:
+
+### JavaScript
+
+Install the JavaScript client with npm.
+
+### Python
+
+Install the Python client with pip.
+
+### JavaScript
+
+Import the JavaScript client in your application.
+
+### Python
+
+Import the Python client in your application.
+
+`sync` names use up to 64 letters, numbers, dashes, or underscores, starting with a letter or number. Synchronization follows reader choices within this page; it does not store a cross-page preference or move focus to another group. Markdown still includes every tab.
+
+## HTML, Markdown, and agents
+
+HTML contains every panel before scripts run. Without JavaScript, all panels remain visible. With JavaScript, Left and Right arrows switch tabs, while Home and End choose the first and last.
+
+The build replaces the tab controls with ordinary Markdown sections. Each `Tab` label becomes a level-three heading, followed by that tab's complete body, in source order. The outer `Tabs` label is for the HTML control and does not appear in Markdown. The first example on this page renders like this in the Markdown twin:
+
+```md
+### HTML
+
+The page has navigation and controls.
+
+### Markdown
+
+The page keeps the content as text.
+```
+
+An agent reading the `.md` page gets every alternative without choosing a tab. Markdown inside each body stays Markdown; supported MDX components expand to their own Markdown forms during the build.
+
+Each `Tab` body accepts ordinary Markdown, including lists, links, and fenced code, plus supported MDX components such as `Callout`, `DocLink`, and `Collapsible`. Put other content inside a `Tab` body. Dynamic MDX expressions and unknown components are not supported.
+
+## Related reading
+
+### Often confused with
+
+- [Collapsibles](https://www.shoalrun.com/author/components/collapsible.md) — A collapsible hides optional detail behind one summary; tabs switch between alternate views of the same content.
+
+- [Content for one format](https://www.shoalrun.com/author/components/only.md) — Tabs show alternate views to every reader; Only limits content to the HTML page or its Markdown twin.

package/agent-docs/author/components/timeline.md

@@ -0,0 +1,74 @@
+---
+id: guide.component.timeline
+title: Timelines
+summary: Show the current milestone and overall progress through a process.
+type: reference
+area: components
+subarea: components-procedures
+canonical: /author/components/timeline
+---
+
+# Timelines
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Timelines
+
+**Updated: 2026-10-19.**
+
+Use `<Timeline>` to show progress through an ordered set of milestones. Set `current` to the `id` of the milestone in progress. Earlier milestones become complete; later milestones become upcoming.
+
+This is a **read-only progress display**. Readers can see the current stage, but they cannot mark milestones complete or move the bar. Update `current` in the source and rebuild the site when the shared process advances. Links inside milestone content work normally.
+
+## When to use it
+
+- Show which stage a product launch or feature rollout has reached.
+- Show where a proposal sits in a draft, review, and approval process.
+- Show progress through a published migration or deprecation plan.
+
+An optional simulation mode could let readers move through the milestones to see each stage of a process. The current component shows only the published state; it has no next, previous, or reset controls.
+
+```mdx
+<Timeline current="review">
+<Milestone id="draft" title="Draft">
+Write the first version of the guide.
+</Milestone>
+<Milestone id="review" title="Review">
+Check the guide with the team.
+</Milestone>
+<Milestone id="publish" title="Publish">
+Make the approved guide available to readers.
+</Milestone>
+</Timeline>
+```
+
+1 of 3 milestones complete. Current: Review.
+
+1. **Complete: Draft**
+
+   Write the first version of the guide.
+
+2. **Current: Review**
+
+   Check the guide with the team.
+
+3. **Upcoming: Publish**
+
+   Make the approved guide available to readers.
+
+The bar counts **completed** milestones. In this example it shows 1 of 3 complete; Review is still in progress. The current milestone also has a visible status label, and the HTML list marks it with `aria-current="step"`. The bar uses a native `<progress>` element with an accessible name. Markdown includes the same progress summary and status labels.
+
+| Attribute | Where       | Required | Meaning                                                                         |
+| --------- | ----------- | -------- | ------------------------------------------------------------------------------- |
+| `current` | `Timeline`  | Yes      | The ID of the milestone in progress.                                            |
+| `id`      | `Milestone` | Yes      | A unique ID using lowercase letters, numbers, and hyphens. Start with a letter. |
+| `title`   | `Milestone` | Yes      | Visible milestone title.                                                        |
+| `date`    | `Milestone` | No       | A real date in `YYYY-MM-DD` form. Rendered as `<time>` in HTML.                 |
+
+Add one or more direct `<Milestone>` children in process order. Each milestone needs body content and can contain ordinary Markdown and supported components.
+
+## HTML, Markdown, and agents
+
+HTML shows the progress bar and milestone list with visible status labels; the current item has `aria-current="step"`. Markdown includes the same progress summary, status labels, and full milestone bodies. An agent can identify the current stage and read every milestone without interpreting the bar.

package/agent-docs/author/components/tooltips.md

@@ -0,0 +1,58 @@
+---
+id: guide.component.tooltip
+title: Tooltips
+summary: Show brief supporting text on hover or keyboard focus, with a tap
+  option for touch readers.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/tooltips
+---
+
+# Tooltips
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Tooltips
+
+**Updated: 2026-10-26.**
+
+Use `<Tooltip>` for brief supporting text beside a term. The text appears when readers hover over or focus the label. Use [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) for click-to-expand explanations, or a [callout](https://www.shoalrun.com/author/components/callout.md) for warnings and instructions that belong in the reading path.
+
+## Syntax
+
+```mdx
+Compare the <Tooltip label="build digest">A fingerprint of the published build's content.</Tooltip> before refreshing your cache.
+```
+
+Compare the build digest (A fingerprint of the published build's content.) before refreshing your cache.
+
+| Attribute | Required | Meaning                                       |
+| --------- | -------- | --------------------------------------------- |
+| `label`   | Yes      | Nonempty text shown on the focusable trigger. |
+
+The body must be one brief plain-text explanation. Links, formatted text, multiple paragraphs, and other components are unsupported. A tooltip may appear inline in a paragraph or as a standalone block.
+
+`<Tooltip>` previously aliased `<InfoHint>`. Use `<InfoHint>` for the original native disclosure behavior.
+
+## HTML, Markdown, and agents
+
+With JavaScript, the label becomes a button linked to its explanation through `aria-describedby`. Hovering or focusing the label opens a popup with `role="tooltip"`. Readers can move the pointer over the popup without closing it. Escape dismisses it while focus stays on the label. Moving focus and the pointer away closes it. Touch readers can tap the label to open or close it, or tap elsewhere to dismiss it.
+
+The popup contains no focusable controls. Use an ordinary link or disclosure when readers need to interact with the explanation. Keep tooltips supplementary; essential warnings, choices, and instructions belong in visible page content.
+
+Without JavaScript, the label and explanation remain visible together in the page. Markdown includes the label and full explanation as ordinary text, so agents do not need hover, focus, or browser scripts. For the inline example above, the Markdown twin reads:
+
+```md
+Compare the build digest (A fingerprint of the published build's content.) before refreshing your cache.
+```
+
+The interaction follows the [WAI tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) and its guidance on [content shown on hover or focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html).
+
+## Related reading
+
+### Often confused with
+
+- [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) — Tooltips open on hover or focus; short definitions use native click-to-expand disclosures.