@superjackfruitlabs/vibekit-docs 0.0.0-stage → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ ## 0.0.4 — 2026-11-15
4
+
5
+ - **MIT licence.** Published under the MIT License (`LICENSE`); it was `UNLICENSED`. The licence covers the code, not the Super Jackfruit Labs names, logos or Captain Jack (the frame's `brand/` marks included).
6
+ - **On npm as `@superjackfruitlabs/vibekit-docs`.** The docs theme is published as `@superjackfruitlabs/vibekit-docs` from this version; previously docs sites vendored the `@superjackfruit/docs-theme` tarballs (`vendor/superjackfruit-docs-theme-*.tgz`). It joins vibekit, the suite's design layer. Every subpath (`/schema`, `/components/*`, `/styles/*`, `/pages/*`) is unchanged.
7
+ - **Peers renamed.** `@superjackfruitlabs/vibekit-frame >=0.0.16 <0.1.0` and `@superjackfruitlabs/vibekit-ui >=0.0.18 <0.1.0` (were `@superjackfruit/frontdoor` and `@superjackfruit/vibekit`). The Starlight plugin and its routes integration are named `@superjackfruitlabs/vibekit-docs` and `@superjackfruitlabs/vibekit-docs/routes`; the component and stylesheet paths it hands Starlight use the new name. Nothing a page shows changed.
8
+ - **Moving a site over:** replace the three `file:vendor/...tgz` dependencies with `^` ranges of the three packages, change `@superjackfruit/docs-theme` to `@superjackfruitlabs/vibekit-docs` in `astro.config.mjs`, `content.config.ts` and every `.mdx` import, and delete `vendor/`.
9
+
10
+ ## 0.0.3
11
+
12
+ - **A site that is not a product.** `sjlDocs({ site: { slug, name, url, docs?, repo, line, wears: 'lab' } })` dresses a docs site that is not a product, such as Treaty, the suite's contracts. The operator decided on 2026-11-14 that Treaty wears the lab's look, not a product colour. The site wears vibekit's `SITE_ACCENTS.lab` (graphite, neutral); the lab's amber appears only in the lab's mark. It shows its own name beside the lab's mark. The street, the switchers and the suite footer show the suite with no product marked as here. Its way out is its landing page, or the lab's home when the docs are the whole site. Footers, the 404, Copy Markdown and Open as Markdown, llms.txt and the edit link all work. BentoHome, CopyPrompt and CaptainJack take the site; Ask sends its slug, which the suite worker knows for `treaty`. See the README.
13
+ - On a non-product site the lab's suite footer takes the site's accent for its own colour (the focus ring, Captain Jack's panel), so the lab's amber stays in the marks.
14
+ - **Fixed:** the Work with an agent prompt no longer runs past its tile. A long address (an llms-full.txt URL) widened the tile's grid column by about 20px at desktop widths, on every site. An e2e test checks 1440, 1100 and 390px.
15
+ - `product:` works exactly as before for every product.
16
+ - Needs vibekit 0.0.17 (for `SITE_ACCENTS`); the workspace vendors it.
17
+ - **Types for the schema.** `src/schema.d.mts` types `sjlDocsSchema` and `statusField`, so a site's `content.config.ts` passes `astro check` (it failed with ts(7016) before).
18
+ - **Tests.** The fixture is also built as Treaty (`fixture/astro.site.config.mjs`, into `dist-site/`), and `test/site.test.ts` checks it. Plugin tests cover the option and its refusals.
19
+
20
+ ## 0.0.2
21
+
22
+ - **A quieter foot.** Only the docs home and the 404 wear frontdoor's full suite footer. Every other page keeps Starlight's previous and next, edit link and last-updated date, then one line: "Part of Super Jackfruit Labs" and a Products switcher that opens the suite's list.
23
+ - **FlowSteps is a tablist.** The range slider is gone. The steps are numbered tabs with one tab stop; Left and Right follow the text direction, Home and End jump, and the arrows stop at either end (`loop` wraps). Back and Next are 44px targets that keep focus at either end. Transitions run only under `prefers-reduced-motion: no-preference`; the stepper works the same with reduced motion. The pattern follows Vercel's UI SDK tabs, focus and motion docs, and lives in `src/client/steps.ts`.
24
+ - **`DecisionReplay`**, a new component: a recorded SuperDispatch placement decision, stepped through with the same tabs, from a JSON file in the site. Nothing to install.
25
+ - **`CopyPrompt`**, a new component: a prompt for a coding agent naming the product's `llms.txt` and `llms-full.txt`. BentoHome shows it in a new Work with an agent tile (`agent`, or `agent={false}`).
26
+ - **Every page as Markdown** at `<page>.md`, and an Open as Markdown link beside Copy Markdown. Both give the same text.
27
+ - **BentoHome**: the Quick start takes a `quickstart` slot, for a quick start that needs nothing installed, and spans the full width. The Quick start's Copy and Copy Markdown announce "Copied". When the clipboard is blocked, the Quick start's Copy selects the command.
28
+ - **Controls.** Captain Jack's Ask button stays focusable while he reads. A theme button with the `hidden` attribute is now hidden; before, its `display` overrode it. On touch screens theme buttons are at least 44px tall.
29
+ - **Tests.** `npm run e2e` drives the fixture in Chrome. The fixture build points `cookie` at Astro's own copy, so it builds in the workspace again.
30
+
31
+ ## 0.0.1
32
+
33
+ The first release, with frontdoor 0.0.15. See frontdoor's CHANGELOG.
package/LICENSE ADDED
@@ -0,0 +1,26 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rakesh Gangwar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ---
24
+
25
+ The MIT License above covers the code. It grants no right to the Super Jackfruit Labs names,
26
+ product names, logos or the Captain Jack character and artwork, which stay with their owner.
package/README.md CHANGED
@@ -1,3 +1,111 @@
1
- # Temporary Holding Version
1
+ # @superjackfruitlabs/vibekit-docs
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The suite's docs design, as one Starlight plugin. A product's docs site sets its title, its sidebar and this:
4
+
5
+ ```js
6
+ // astro.config.mjs
7
+ import starlight from '@astrojs/starlight';
8
+ import sjlDocs from '@superjackfruitlabs/vibekit-docs';
9
+
10
+ starlight({
11
+ title: 'SuperDispatch',
12
+ plugins: [sjlDocs({ product: 'superdispatch', status: 'wet paint' })],
13
+ sidebar: [/* Start, Use it, Build on it, Run it, Reference */],
14
+ });
15
+ ```
16
+
17
+ ```ts
18
+ // src/content.config.ts: Starlight's schema plus `status:`
19
+ import { defineCollection } from 'astro:content';
20
+ import { docsLoader } from '@astrojs/starlight/loaders';
21
+ import { sjlDocsSchema } from '@superjackfruitlabs/vibekit-docs/schema';
22
+
23
+ export const collections = { docs: defineCollection({ loader: docsLoader(), schema: sjlDocsSchema() }) };
24
+ ```
25
+
26
+ ## A site that is not a product
27
+
28
+ A docs site for something the suite shares but does not sell, such as Treaty (the suite's contracts), names itself with `site` instead of `product`, and wears the lab's look:
29
+
30
+ ```js
31
+ sjlDocs({
32
+ site: {
33
+ slug: 'treaty',
34
+ name: 'Treaty',
35
+ url: 'https://treaty.superjackfruit.com',
36
+ repo: 'https://github.com/SuperJackfruitLabs/treaty',
37
+ line: "The suite's contracts as code.",
38
+ wears: 'lab',
39
+ },
40
+ status: 'half-lit',
41
+ llms: { description: '…' },
42
+ })
43
+ ```
44
+
45
+ - **Colours.** The site wears vibekit's `SITE_ACCENTS.lab`, graphite, a neutral accent (vibekit 0.0.17 or later). The lab's amber sits inside vibekit's signal hue band, so it never becomes an accent token. It appears only in the lab's mark, which is an image.
46
+ - **The header** shows the site's own name beside the lab's mark. Treaty has no mark of its own, and the theme never draws one. The street shows the whole suite with no house raised, and the switchers mark no product as here.
47
+ - **The way out.** The street, the home and the 404 link to the site's landing page. When the docs are the whole site (no `docs` address apart from `url`), they link to the lab's home instead.
48
+ - **The foot.** The docs home and the 404 wear the lab's suite footer, with no product tile marked, plus the site's own source and llms.txt links. Content pages keep the quiet line.
49
+ - **Everything else** works as on a product's site: the status badge, Copy Markdown and Open as Markdown, every page at `<page>.md`, llms.txt (its name and `line` by default), the edit link from `repo`, the 404 and the sidebar check.
50
+ - **Components.** `BentoHome`, `CopyPrompt`, `CaptainJack`, `Switcher` and the rest take the site as they take a product. Ask Captain Jack sends the site's `slug` as the product. The suite worker answers from that site's docs only when it lists the slug (it lists `treaty`). For any other site, pass `ask={false}` until the worker knows it.
51
+ - **Rules.** Give `product` or `site`, not both. `slug` is lowercase letters, digits and dashes, and never a product's slug or `lab`. `name`, `line` and an `https://` `url` are required; `docs` and `repo` are optional. `wears` is `'lab'`.
52
+
53
+ ## What the plugin brings
54
+
55
+ - **Colours from vibekit.** It reads the product's accent from vibekit's `PRODUCT_ACCENTS` and its Daylight values from `accents.css`, for light and dark. Every site shares one neutral grey scale, so the products differ only in their accent. No product colour is typed in this package.
56
+ - **Faces, self-hosted.** Bricolage Grotesque for display, IBM Plex Sans for body text and IBM Plex Mono for code. The font files are bundled into the site, so no page fetches a font from Google.
57
+ - **The header.** The site title shows the product's mark and name, plus the site's status when the `status` option is set. Above it, the street is the suite map: one house per product, leading to that product's docs. On a phone the street folds into a product switcher. The header also links to the product's landing page.
58
+ - **Page titles.** Each page gets a status badge from its frontmatter `status:`, a Copy Markdown button and an Open as Markdown link.
59
+ - **Every page as Markdown.** Each page is also served at its own address plus `.md` (`/start/first-steps.md`, `/index.md` for the home): the title and the body as written, MDX imports dropped. It is the same text Copy Markdown copies. `starlight-llms-txt` serves only the whole-site files, so the theme adds this route itself.
60
+ - **The foot of the page.** Starlight's own edit link, last-updated date and previous/next links come first. The docs home and the 404 then wear frontdoor's full suite footer. Every other page ends with one quiet line instead: "Part of Super Jackfruit Labs" and a Products switcher that opens the suite's list.
61
+ - **A 404 with character**: "You've wandered off the street", with search, a link to the docs home and a link to the landing page.
62
+ - **Defaults**: `starlight-llms-txt` is on (`llms: false` turns it off), `editLink` points at the product's repo (`docsDir` sets the folder, `docs-site/` by default), and `lastUpdated: true`. A site's own settings win.
63
+ - **A sidebar check.** The build warns when the top-level groups are not Start / Use it / Build on it / Run it / Reference, in that order. A site may leave groups out.
64
+
65
+ ## Status words
66
+
67
+ | Word | Means |
68
+ |---|---|
69
+ | lit & steady | In production, stable, relied on daily. |
70
+ | lights on | In production, still changing. |
71
+ | half-lit | Works, with known gaps the page names. |
72
+ | wet paint | New or experimental. |
73
+
74
+ Each badge is filled with vibekit's mood colours, never the accent.
75
+
76
+ ## Components for pages
77
+
78
+ Import these in `.mdx` from `@superjackfruitlabs/vibekit-docs/components/<Name>.astro`.
79
+
80
+ - `BentoHome`: the docs home, for `index.mdx` with `template: splash` and no `hero`. It takes `claim`, `sub`, `actions`, `quickstart` (`{ command, label?, note? }`), `status`, `ask` (`{ examples }`, or `false`), `agent` (`{ task?, prompt? }`, or `false`), `flowTitle` and `map`. Whatever you put inside it fills the "how it works" tile. An element with `slot="quickstart"` replaces the Quick start's command, for a quick start that needs nothing installed, such as a `DecisionReplay`; `quickstart` then takes only `label` and `note`.
81
+ - `FlowSteps`: a process the reader steps through: numbered steps as a tablist, a lane per step that fills in as the steps are reached, the selected step's panel, and Back and Next. It never moves by itself.
82
+ - `DecisionReplay`: a recorded placement decision, replayed in the same steps: the card ready, every candidate with each filter's result and reason code, the scores, the hold and the claim. Pass `decision`, a JSON file in the site holding a decision as SuperDispatch's operator API returns it, and `source`, a line saying where it was recorded.
83
+ - `CopyPrompt`: a prompt to paste into a coding agent. It tells the agent to read the product's `llms.txt` and `llms-full.txt`, then do `task`. BentoHome shows it in its Work with an agent tile.
84
+ - `Switcher`: the product switcher (the street on a phone, and the foot of a content page).
85
+ - `CaptainJack`: the Ask box. It sends the question to the suite worker at this site's own `/captain/`. Captain Jack answers only from the product's docs and the lab's checked claims, and links each docs passage he cites. When the docs don't cover a question, he says "I don't know".
86
+ - `Tip`, `HeadsUp`, `WetPaint`, `JackAside`: the callouts.
87
+ - `StatusBadge`: a status word as a pill.
88
+
89
+ ## Steps, keys and focus
90
+
91
+ `FlowSteps` and `DecisionReplay` share one pattern (`src/client/steps.ts`), after the tabs, focus and motion pages of Vercel's UI SDK docs:
92
+
93
+ - The steps are a `tablist` with one tab stop: the selected step's tab has `tabindex="0"`, the rest `-1`.
94
+ - Left and Right move to the next or previous step in the page's text direction, Home and End to the first and last. The arrows stop at either end (`FlowSteps` takes `loop` to wrap). Moving selects the step.
95
+ - Each tab has `aria-selected` and `aria-controls`; its panel has `role="tabpanel"` and `aria-labelledby`. Only the selected panel is shown.
96
+ - Back and Next are at least 44px square. At either end they are `aria-disabled`, not `disabled`, so focus stays on the button.
97
+ - Nothing moves by itself. Transitions run only under `prefers-reduced-motion: no-preference`.
98
+ - Every tab, panel and button has a visible focus ring. Tabs are at least 44px.
99
+ - Without JavaScript, every step's panel is written out and the tablist stays hidden.
100
+
101
+ Copy buttons (Copy Markdown, Copy prompt, the Quick start's Copy) say "Copied" and announce it in a live region. Focus stays on the button. On touch screens every theme button is at least 44px tall.
102
+
103
+ ## Peers
104
+
105
+ `astro` 7, `@astrojs/starlight` 0.42, `starlight-llms-txt` 0.12, `@superjackfruitlabs/vibekit-ui` 0.0.18 or later, and `@superjackfruitlabs/vibekit-frame` 0.0.16 or later (product list, marks and suite footer). All three are on npm; install them with `npm install @superjackfruitlabs/vibekit-docs @superjackfruitlabs/vibekit-frame @superjackfruitlabs/vibekit-ui`. Until 0.0.4 they were vendored as `@superjackfruit/docs-theme`, `@superjackfruit/frontdoor` and `@superjackfruit/vibekit` tarballs.
106
+
107
+ ## Tests
108
+
109
+ `npm test` builds `fixture/`, a small Starlight site that wears the theme. It then checks that build, the plugin's config, the tokens against vibekit's own CSS, and contrast for every product in light and dark.
110
+
111
+ `npm run e2e` builds the fixture and drives it in an installed Chrome (Playwright, `channel: 'chrome'`): the step keys and focus, right-to-left, reduced motion, no JavaScript, the copy buttons, the `.md` pages and the foot of the page.
package/index.ts ADDED
@@ -0,0 +1,180 @@
1
+ // @superjackfruitlabs/vibekit-docs: the suite's docs design as one Starlight plugin. A site's whole
2
+ // design config is
3
+ //
4
+ // starlight({ title, plugins: [sjlDocs({ product: 'superdispatch' })], sidebar })
5
+ //
6
+ // and the plugin brings the rest. A site that is not a product (Treaty, the suite's contracts) names
7
+ // itself instead, and wears the lab's look:
8
+ //
9
+ // sjlDocs({ site: { slug: 'treaty', name: 'Treaty', url, repo, line, wears: 'lab' } })
10
+ //
11
+ // The theme brings vibekit's colours for the product (or the site's accent), the shared fonts (self-hosted),
12
+ // the site title, the street as the suite map, the status badges, Copy Markdown and Open as
13
+ // Markdown (every page at <page>.md), the footers, the 404, llms.txt, the edit link and
14
+ // last-updated dates, and a check that the sidebar uses the suite's five groups. Components for
15
+ // pages (BentoHome, CaptainJack, CopyPrompt, FlowSteps, DecisionReplay, the callouts) are
16
+ // imported from '@superjackfruitlabs/vibekit-docs/components/<Name>.astro'.
17
+ //
18
+ // TypeScript on purpose, like starlight-llms-txt: Node will not run TypeScript from node_modules,
19
+ // so Astro loads a config that imports this file through Vite, which compiles it.
20
+ import { readFileSync } from 'node:fs';
21
+ import { createRequire } from 'node:module';
22
+ import starlightLlmsTxt from 'starlight-llms-txt';
23
+ import { PRODUCT_ACCENTS, SITE_ACCENTS } from '@superjackfruitlabs/vibekit-ui/appearance';
24
+ import { ORDER, PRODUCTS, SITES, type Slug } from '@superjackfruitlabs/vibekit-frame/data';
25
+ import type { StarlightPlugin } from '@astrojs/starlight/types';
26
+ import { sidebarWarnings } from './src/sidebar.mjs';
27
+ import { statusOf, themeCss } from './src/tokens.mjs';
28
+
29
+ const require = createRequire(import.meta.url);
30
+ const C = (name: string) => `@superjackfruitlabs/vibekit-docs/components/${name}.astro`;
31
+
32
+ /** The theme's CSS for one vibekit accent, light and dark. */
33
+ export function accentCss(accent: string): string {
34
+ const read = (spec: string) => readFileSync(require.resolve(spec), 'utf8');
35
+ return themeCss(read('@superjackfruitlabs/vibekit-ui/accents.css'), read('@superjackfruitlabs/vibekit-ui/tokens.css'), accent);
36
+ }
37
+
38
+ /** The theme's CSS for one product: vibekit's tokens for it, light and dark. */
39
+ export function productCss(product: string): string {
40
+ const accent = (PRODUCT_ACCENTS as Record<string, string>)[product];
41
+ if (!accent) throw new Error(`docs-theme: vibekit names no accent for "${product}"`);
42
+ return accentCss(accent);
43
+ }
44
+
45
+ /** Whose look a non-product site wears. Only the lab's, for now. */
46
+ export type Wears = 'lab';
47
+
48
+ /**
49
+ * A docs site that is not a product: it is never a house on the street, and it wears the look of
50
+ * `wears` (vibekit's SITE_ACCENTS names the accent; the lab's is graphite) and that site's mark.
51
+ */
52
+ export interface SjlSite {
53
+ /** A short id ('treaty'): lowercase letters, digits and dashes, and no product's slug. */
54
+ slug: string;
55
+ /** The name in the header and the page titles ('Treaty'). */
56
+ name: string;
57
+ /** The site's address. When it has a landing page of its own, `docs` is the docs' address. */
58
+ url: string;
59
+ /** The docs' address, when it is not `url`. */
60
+ docs?: string;
61
+ /** The repository, for the edit link and the Source link (null when there is none). */
62
+ repo: string | null;
63
+ /** One line saying what it is, for llms.txt and the street's title. */
64
+ line: string;
65
+ wears: Wears;
66
+ }
67
+
68
+ /** The site record the components read (virtual:sjl-docs/theme): what they need of a product, for a site. */
69
+ export function siteRecord(site: SjlSite) {
70
+ const where = `docs-theme: site "${site?.slug}"`;
71
+ if (!site || typeof site.slug !== 'string' || !/^[a-z][a-z0-9-]*$/.test(site.slug)) throw new Error(`${where}: slug must be lowercase letters, digits and dashes`);
72
+ if (site.slug in SITES) throw new Error(`${where}: "${site.slug}" is a product or the lab; use product: '${site.slug}' instead`);
73
+ for (const k of ['name', 'line'] as const) if (typeof site[k] !== 'string' || !site[k].trim()) throw new Error(`${where}: ${k} is required`);
74
+ for (const k of ['url', 'docs', 'repo'] as const) {
75
+ const v = site[k];
76
+ if (v == null) { if (k === 'url') throw new Error(`${where}: url is required`); continue; }
77
+ if (typeof v !== 'string' || !/^https:\/\/[^/\s]+/.test(v)) throw new Error(`${where}: ${k} must be an https:// address`);
78
+ }
79
+ const lab = SITES[site.wears as 'lab'];
80
+ const accent = (SITE_ACCENTS as Record<string, string>)[site.wears];
81
+ if (site.wears !== 'lab' || !lab || !accent) throw new Error(`${where}: wears must be 'lab'`);
82
+ const url = site.url.replace(/\/$/, '');
83
+ const docs = (site.docs ?? site.url).replace(/\/$/, '');
84
+ return {
85
+ slug: site.slug, name: site.name.trim(), line: site.line.trim(), url, docs, repo: site.repo ?? null,
86
+ wears: site.wears, accent,
87
+ // The way out of the docs: the site's own landing page, or, when the docs are the whole site, the lab's.
88
+ landing: docs === url ? lab.url : url,
89
+ };
90
+ }
91
+
92
+ export interface SjlDocsOptions {
93
+ /** The product's slug, as in frontdoor's product list ('superdispatch'). Give this or `site`. */
94
+ product?: Slug;
95
+ /** A docs site that is not a product, such as Treaty. Give this or `product`. */
96
+ site?: SjlSite;
97
+ /** The site's status word, beside its title: "wet paint", "half-lit", "lights on" or "lit & steady". */
98
+ status?: string;
99
+ /** The docs site's folder in the repo, for the edit link (default 'docs-site/'). */
100
+ docsDir?: string;
101
+ /** Options for starlight-llms-txt (on by default), or false to leave it off. */
102
+ llms?: false | { description?: string; details?: string; optionalLinks?: { label: string; url: string; description?: string }[] };
103
+ }
104
+
105
+ export default function sjlDocs(options: SjlDocsOptions): StarlightPlugin {
106
+ const { product, docsDir = 'docs-site/' } = options ?? ({} as SjlDocsOptions);
107
+ if (product !== undefined && options.site !== undefined) throw new Error('docs-theme: give product or site, not both');
108
+ const site = options?.site === undefined ? null : siteRecord(options.site);
109
+ const prod = site ? null : (PRODUCTS as Record<string, (typeof PRODUCTS)[Slug]>)[product as string];
110
+ if (!site && !prod) throw new Error(`docs-theme: unknown product "${product}"; one of ${ORDER.join(', ')}, or a site: { … }`);
111
+ const me = site ?? { slug: product as string, name: prod!.name, line: prod!.line, url: prod!.url, repo: prod!.repo };
112
+ const status = options.status === undefined ? undefined : statusOf(options.status);
113
+ if (options.status !== undefined && !status) throw new Error(`docs-theme: status "${options.status}" is not one of wet paint, half-lit, lights on, lit & steady`);
114
+ const llms = options.llms === false ? null : starlightLlmsTxt({
115
+ projectName: me.name,
116
+ description: options.llms?.description ?? `${me.name}: ${me.line}`,
117
+ ...(options.llms?.details ? { details: options.llms.details } : {}),
118
+ optionalLinks: options.llms?.optionalLinks ?? [
119
+ ...(site ? (site.landing === site.url ? [{ label: me.name, url: me.url, description: 'The site.' }] : []) : [{ label: me.name, url: me.url, description: 'The product site.' }]),
120
+ ...(me.repo ? [{ label: 'Source', url: me.repo, description: `The ${me.name} repository.` }] : []),
121
+ ],
122
+ });
123
+
124
+ return {
125
+ name: '@superjackfruitlabs/vibekit-docs',
126
+ hooks: {
127
+ async 'config:setup'(ctx) {
128
+ const { config, updateConfig, addIntegration, logger } = ctx;
129
+ for (const w of sidebarWarnings(config.sidebar)) logger.warn(w);
130
+
131
+ const theme = { product: site ? null : me.slug, site, name: me.name, landing: site ? site.landing : me.url, status: status ?? null };
132
+ updateConfig({
133
+ components: {
134
+ SiteTitle: C('SiteTitle'),
135
+ Header: C('Header'),
136
+ PageTitle: C('PageTitle'),
137
+ Footer: C('Footer'),
138
+ ...config.components,
139
+ },
140
+ customCss: ['@superjackfruitlabs/vibekit-docs/styles/fonts.css', '@superjackfruitlabs/vibekit-docs/styles/theme.css', ...(config.customCss ?? [])],
141
+ head: [
142
+ { tag: 'style', attrs: { 'data-sjl-docs': me.slug }, content: site ? accentCss(site.accent) : productCss(me.slug) },
143
+ ...(config.head ?? []),
144
+ ],
145
+ editLink: config.editLink?.baseUrl ? config.editLink : me.repo ? { baseUrl: `${me.repo}/edit/main/${docsDir}` } : config.editLink,
146
+ lastUpdated: config.lastUpdated ?? true,
147
+ disable404Route: true,
148
+ });
149
+
150
+ addIntegration({
151
+ name: '@superjackfruitlabs/vibekit-docs/routes',
152
+ hooks: {
153
+ 'astro:config:setup'({ injectRoute, updateConfig: updateAstro }) {
154
+ injectRoute({ pattern: '404', entrypoint: '@superjackfruitlabs/vibekit-docs/pages/404.astro', prerender: true });
155
+ // Every page as Markdown at `<page>.md` (Open as Markdown links it).
156
+ injectRoute({ pattern: '/[...slug].md', entrypoint: '@superjackfruitlabs/vibekit-docs/pages/markdown.ts', prerender: true });
157
+ // The theme's settings, for its components (virtual module: no file in the site).
158
+ updateAstro({ vite: { plugins: [virtualTheme(theme)] } });
159
+ },
160
+ },
161
+ });
162
+
163
+ if (llms) {
164
+ const hooks = llms.hooks as Record<string, ((c: typeof ctx) => unknown) | undefined>;
165
+ const setup = hooks['config:setup'] ?? hooks.setup;
166
+ await setup?.(ctx);
167
+ }
168
+ },
169
+ },
170
+ };
171
+ }
172
+
173
+ function virtualTheme(theme: object) {
174
+ const id = 'virtual:sjl-docs/theme';
175
+ return {
176
+ name: 'sjl-docs-theme',
177
+ resolveId: (x: string) => (x === id ? `\0${id}` : undefined),
178
+ load: (x: string) => (x === `\0${id}` ? `export default ${JSON.stringify(theme)};` : undefined),
179
+ };
180
+ }
package/package.json CHANGED
@@ -1,6 +1,55 @@
1
1
  {
2
2
  "name": "@superjackfruitlabs/vibekit-docs",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.4",
4
+ "type": "module",
5
+ "description": "The Super Jackfruit Labs docs theme: one Starlight plugin that dresses a product's docs site in the suite's design, from vibekit's colours to Captain Jack.",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/SuperJackfruitLabs/frontdoor.git",
10
+ "directory": "packages/docs-theme"
11
+ },
12
+ "exports": {
13
+ ".": "./index.ts",
14
+ "./schema": "./src/schema.mjs",
15
+ "./components/*": "./src/components/*",
16
+ "./styles/*": "./src/styles/*",
17
+ "./pages/*": "./src/pages/*",
18
+ "./package.json": "./package.json"
19
+ },
20
+ "files": [
21
+ "index.ts",
22
+ "src",
23
+ "README.md",
24
+ "CHANGELOG.md"
25
+ ],
26
+ "scripts": {
27
+ "test": "npm run fixture && vitest run",
28
+ "fixture": "cd fixture && astro build && astro build --config astro.site.config.mjs",
29
+ "e2e": "npm run fixture && playwright test"
30
+ },
31
+ "dependencies": {
32
+ "@fontsource-variable/bricolage-grotesque": "5.3.0",
33
+ "@fontsource/ibm-plex-mono": "5.3.0",
34
+ "@fontsource/ibm-plex-sans": "5.3.0"
35
+ },
36
+ "peerDependencies": {
37
+ "@astrojs/starlight": ">=0.42.0 <0.43.0",
38
+ "@superjackfruitlabs/vibekit-frame": ">=0.0.16 <0.1.0",
39
+ "@superjackfruitlabs/vibekit-ui": ">=0.0.18 <0.1.0",
40
+ "astro": ">=7.3.0",
41
+ "starlight-llms-txt": ">=0.12.0"
42
+ },
43
+ "devDependencies": {
44
+ "@astrojs/starlight": "0.42.11",
45
+ "@playwright/test": "^1.64.1",
46
+ "@superjackfruitlabs/vibekit-frame": "0.0.16",
47
+ "@superjackfruitlabs/vibekit-ui": "file:../frame/vendor/superjackfruitlabs-vibekit-ui-0.0.18.tgz",
48
+ "astro": "7.4.11",
49
+ "starlight-llms-txt": "0.12.0"
50
+ },
51
+ "publishConfig": {
52
+ "access": "public",
53
+ "registry": "https://registry.npmjs.org/"
54
+ }
55
+ }
@@ -0,0 +1,80 @@
1
+ // The step pattern FlowSteps and DecisionReplay share: a tablist of numbered steps, one panel per
2
+ // step, and Back and Next. It follows the tabs pattern in Vercel's UI SDK docs
3
+ // (ui-sdk.dev/docs/components/tabs, /docs/core/behaviors/focus):
4
+ //
5
+ // - one tab stop for the group (a roving tabindex: the selected step's tab is 0, the rest -1);
6
+ // - Left and Right move along the steps in the page's text direction, Home and End go to the
7
+ // first and last step, and the arrows stop at either end unless the component asks to loop;
8
+ // - moving to a tab selects it (aria-selected) and shows its panel (aria-controls, role
9
+ // tabpanel); the other panels are hidden;
10
+ // - Back and Next stay focusable at either end (aria-disabled, not disabled), so focus never
11
+ // falls to the page when a button runs out of steps;
12
+ // - nothing moves by itself.
13
+ //
14
+ // The markup arrives server-rendered with every panel visible and the tablist and buttons hidden,
15
+ // so without JavaScript the reader gets every step written out. bindSteps turns it live.
16
+
17
+ export interface StepsOptions {
18
+ /** Wrap from the last step to the first and back. Off by default. */
19
+ loop?: boolean;
20
+ /** Called after every change of step, with the new index. */
21
+ onStep?: (index: number) => void;
22
+ }
23
+
24
+ export function bindSteps(root: HTMLElement, options: StepsOptions = {}): { select: (i: number, focus?: boolean) => void } | null {
25
+ const list = root.querySelector<HTMLElement>('[role="tablist"]');
26
+ if (!list) return null;
27
+ const tabs = [...list.querySelectorAll<HTMLElement>('[role="tab"]')];
28
+ const panels = tabs.map((t) => document.getElementById(t.getAttribute('aria-controls') ?? ''));
29
+ if (!tabs.length || panels.some((p) => !p)) return null;
30
+ const back = root.querySelector<HTMLButtonElement>('[data-step="back"]');
31
+ const next = root.querySelector<HTMLButtonElement>('[data-step="next"]');
32
+ const count = root.querySelector<HTMLElement>('[data-step="count"]');
33
+ const controls = root.querySelector<HTMLElement>('[data-step="controls"]');
34
+ const n = tabs.length;
35
+ let current = Math.max(0, tabs.findIndex((t) => t.getAttribute('aria-selected') === 'true'));
36
+
37
+ const select = (i: number, focus = false) => {
38
+ current = Math.max(0, Math.min(n - 1, i));
39
+ tabs.forEach((t, k) => {
40
+ t.setAttribute('aria-selected', String(k === current));
41
+ t.tabIndex = k === current ? 0 : -1;
42
+ });
43
+ panels.forEach((p, k) => { p!.hidden = k !== current; });
44
+ back?.setAttribute('aria-disabled', String(current === 0));
45
+ next?.setAttribute('aria-disabled', String(current === n - 1));
46
+ if (count) count.textContent = `Step ${current + 1} of ${n}`;
47
+ root.dataset.current = String(current);
48
+ if (focus) tabs[current]!.focus();
49
+ options.onStep?.(current);
50
+ };
51
+
52
+ list.addEventListener('keydown', (e) => {
53
+ if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return;
54
+ const from = tabs.indexOf(e.target as HTMLElement);
55
+ if (from < 0) return;
56
+ const rtl = getComputedStyle(list).direction === 'rtl';
57
+ let to: number;
58
+ switch (e.key) {
59
+ case 'ArrowRight': to = from + (rtl ? -1 : 1); break;
60
+ case 'ArrowLeft': to = from + (rtl ? 1 : -1); break;
61
+ case 'Home': to = 0; break;
62
+ case 'End': to = n - 1; break;
63
+ default: return;
64
+ }
65
+ e.preventDefault();
66
+ if (options.loop) to = (to + n) % n;
67
+ if (to < 0 || to >= n || to === from) return;
68
+ select(to, true);
69
+ });
70
+ tabs.forEach((t, k) => t.addEventListener('click', () => select(k)));
71
+ // Focus stays on the button pressed: a step change never moves it.
72
+ back?.addEventListener('click', () => { if (current > 0) select(current - 1); });
73
+ next?.addEventListener('click', () => { if (current < n - 1) select(current + 1); });
74
+
75
+ list.hidden = false;
76
+ if (controls) controls.hidden = false;
77
+ root.classList.add('live');
78
+ select(current);
79
+ return { select };
80
+ }