@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/organisms/navigation/docs-sidebar.pidl.json

@@ -0,0 +1,264 @@
+{
+    "kind": "component",
+    "id": "ui.docs-sidebar",
+    "name": "DocsSidebar",
+    "displayName": "Docs sidebar",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "navigation",
+    "studioReady": false,
+    "bidi": true,
+    "description": "Nested docs navigation tree. Renders a <nav> landmark around real nested <ul>/<li> lists of <a href> links, with native <button aria-expanded> disclosures for groups. The link matching the router's path carries aria-current=\"page\"; the ancestor chain of that link is force-expanded on mount and on every route change. Collapse/expand state persists to localStorage under a caller-supplied key, degrading silently when storage is unavailable. NO search or filtering — that is <CommandPalette>'s job. studioReady is FALSE on purpose: the tree is a data prop and the active state comes from the live router, so there is nothing meaningful to author or preview on a canvas.",
+    "props": [
+        {
+            "name": "items",
+            "label": "Navigation tree",
+            "editor": {
+                "tab": "content",
+                "type": "array"
+            },
+            "type": "DocsSidebarItem[]",
+            "default": [],
+            "itemSchema": {
+                "label": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Visible label. Also the fallback persistence key for a group — see `id`. An entry with a blank label is dropped."
+                },
+                "href": {
+                    "type": "string",
+                    "description": "Destination path. Matched against the router's path with EXACT string equality, so it must be written the way the router reports it (no trailing slash). Values rejected by isSafeHref are dropped with a DEV warning. Omit for a pure grouping heading."
+                },
+                "items": {
+                    "type": "DocsSidebarItem[]",
+                    "description": "Child entries. Presence is what makes an entry a group. An entry with BOTH href and items is a section landing page: it renders a link and a separate disclosure button as siblings."
+                },
+                "id": {
+                    "type": "string",
+                    "description": "Stable persistence key for this group's expanded state. Defaults to the '/'-joined chain of ancestor labels plus this entry's own label. Set it to keep a reader's collapsed state across a label rename, or to disambiguate two groups that share a label path."
+                },
+                "defaultOpen": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Expanded on first visit, before anything is persisted. Defaults to true: a docs sidebar that opens fully collapsed hides the navigation it exists to provide."
+                },
+                "prefetch": {
+                    "type": "'none' | 'hover' | 'visible' | 'eager'",
+                    "default": "none",
+                    "description": "Prefetch strategy for this link. Requires a mounted router; ignored otherwise."
+                }
+            },
+            "description": "The navigation tree, depth-unbounded. Entries are filtered recursively before any DOM is built: a labelless entry, an entry with neither a usable href nor children, and a group whose whole subtree is unrenderable (items: [], or nothing but rejected entries) are all dropped — so the component never ships a disclosure button that expands to an empty list."
+        },
+        {
+            "name": "label",
+            "label": "Landmark name",
+            "type": "string",
+            "default": "Docs",
+            "placeholder": "Docs",
+            "description": "Accessible name for the <nav> landmark. Always applied, never optional: a docs page typically holds several <nav> elements — site header, this sidebar, the table of contents — and the name is what lets a screen-reader user tell them apart in a landmark list. A whitespace-only value falls back to the default rather than producing an empty accessible name."
+        },
+        {
+            "name": "title",
+            "label": "Title",
+            "editor": {
+                "tab": "content"
+            },
+            "type": "string",
+            "required": false,
+            "description": "Optional visible title above the tree, rendered as a real <Heading> so it joins the page's heading outline. Omit it in a layout that already labels the sidebar column."
+        },
+        {
+            "name": "titleLevel",
+            "label": "Title level",
+            "editor": {
+                "tab": "settings"
+            },
+            "type": "number",
+            "default": 2,
+            "description": "Heading level for `title`, 1-6. Pick the level that fits the page's real outline — the sidebar sits beside an article, so it is usually a peer of the article's own h2."
+        },
+        {
+            "name": "storageKey",
+            "label": "Storage key",
+            "editor": {
+                "tab": "settings"
+            },
+            "type": "string | null",
+            "default": "pithy:docs-sidebar",
+            "description": "localStorage key for the collapse/expand state. Pass null to disable persistence entirely — nothing is read and nothing is written. Two sidebars on one page MUST be given distinct keys or they overwrite each other."
+        },
+        {
+            "name": "class",
+            "label": "Extra classes",
+            "editor": {
+                "tab": "settings"
+            },
+            "type": "string",
+            "required": false,
+            "description": "Extra class names appended after 'ui-docs-sidebar'."
+        },
+        {
+            "name": "id",
+            "label": "Element id",
+            "editor": {
+                "tab": "settings"
+            },
+            "type": "string",
+            "required": false,
+            "description": "id for the <nav> element — useful as a skip-link target."
+        }
+    ],
+    "slots": [],
+    "tokens": {
+        "typography": "--font-size-sm + --line-height-body (tree text), --font-weight-semibold (current link, current group), --font-weight-medium (group labels, via <Text>)",
+        "color": "--color-text-muted (rest), --color-text (hover, current group), --color-primary via --_docs-sidebar-accent (current link text, current rail, hover/selected tint), --color-divider via --_docs-sidebar-rail (sublist guide rail)",
+        "spacing": "--space-xs (entry gap, link/toggle block padding, chevron gap, sublist offset), --space-sm (link/toggle inline padding, sublist indent, title margin)",
+        "border": "--border-width-thin + --border-style-solid (sublist guide rail), --border-width-medium (current-link accent rail)",
+        "radius": "--radius-sm (link and toggle boxes), --radius-pill (current-link accent rail)",
+        "control": "--control-min-touch (min block size on every link and toggle, and min inline size on the icon-only toggle) — WCAG 2.5.5",
+        "focus": "--focus-ring-width / --focus-ring-offset / --ring-color via the a11y focus-ring mixin on :focus-visible",
+        "state": "--state-hover-opacity and --state-selected-opacity via the a11y state-background mixin",
+        "motion": "--motion-transition-color / --motion-transition-background (links, toggles) and --motion-transition-transform (chevron), all inside prefers-reduced-motion: no-preference"
+    },
+    "spacing": {
+        "entry-gap": "--space-xs (Lovers) — sibling entries read as one continuous track, not as separate cards",
+        "group-to-children": "--space-xs block-start on the sublist (Lovers) — a group and its own contents are inseparable",
+        "sublist-indent": "--space-sm inline (Close Friends) — a child belongs to the group above it; depth reads from the indent plus the guide rail, never from a size or colour change",
+        "label-to-chevron": "--space-xs (Lovers) — a control and its own affordance",
+        "title-to-tree": "--space-sm block-end (Close Friends) — a title and the list it names",
+        "control-padding": "--space-xs block / --space-sm inline, on top of a --control-min-touch floor — enough hit area at every container width without turning the tree into a button stack"
+    },
+    "constraints": [
+        "The tree comes from the `items` prop — the component takes NO children and declares NO slot",
+        "SEARCH AND FILTERING ARE OUT OF SCOPE. A docs sidebar is a fixed map of the documentation; searching it is <CommandPalette>'s job, and putting a field here would duplicate that component's index, filter and combobox semantics",
+        "href is matched with EXACT string equality against the router path — the same predicate routerLink's exactMatch uses, character for character. Normalising on one side only would let the two disagree, and the disagreement would surface as an expanded group with no aria-current anywhere",
+        "A group may be a link AND a group. It renders an <a> and a <button> as siblings inside one row, because a single control cannot both navigate and toggle: a <button> cannot be followed to a URL, and an <a> carrying aria-expanded would claim to expand something while navigating away",
+        "Collapsed subtrees are `hidden`, which resolves to display:none — their links leave the tab order entirely rather than becoming invisible tab stops. `.ui-docs-sidebar-list` sets display:flex and an author display BEATS the UA [hidden] rule, so the stylesheet restates `&[hidden] { display: none }` explicitly; without it every collapsed group would stay visible and tabbable",
+        "Expansion precedence on mount: the active route's ancestor chain (forced) > persisted state > item.defaultOpen > true",
+        "The force-expand is NEVER written back to storage — it is a view decision for the current route, and persisting it would silently erase the reader's own collapse. Only a click on a disclosure button writes",
+        "Force-expand re-runs only when the ACTIVE ENTRY CHANGES, so collapsing the group you are currently inside stays collapsed until you navigate elsewhere",
+        "localStorage is guarded three ways: an SSR check, a try/catch around the ACCESS itself (some embedders and Safari-with-cookies-blocked throw on merely touching window.localStorage, so wrapping only getItem is not enough), and per-key boolean filtering so a corrupt or version-skewed blob contributes its valid entries instead of poisoning the map. Every failure degrades to defaults; none throws",
+        "Writes are best-effort — setItem throws on quota exhaustion and in Safari private mode, and neither is worth failing a click over",
+        "storageKey defaults to a single shared key, so two sidebars on one page MUST be given distinct keys (or null)",
+        "Group persistence keys default to the '/'-joined ancestor label chain; a duplicate key DEV-warns and the two groups share one persisted state until one is given an explicit id",
+        "With a mounted router, aria-current is owned by the routerLink directive; with no router the component sets it from window.location.pathname and re-syncs on popstate. Exactly one of the two ever writes it",
+        "Every anchor is tagged data-router-link / data-prefetch / exact-match unconditionally, so a router that mounts AFTER the sidebar is built still binds the links via setGlobalRouter → bindExistingRouterLinks — and binds them with the same exact-match semantics",
+        "destroy() removes every toggle listener, unsubscribes from the router, cleans up router directives on every anchor, and empties the nav; a second call is a no-op"
+    ],
+    "a11y": [
+        "Implements the WAI-ARIA APG *Disclosure Navigation* pattern: native <a href> links and native <button aria-expanded> disclosures, every one of them in the natural tab order",
+        "NOT the APG treeview pattern, and that is the non-obvious call: role=\"treeitem\" on an <a href> OVERRIDES the implicit link role, so every entry would drop out of the screen-reader links rotor and stop being announced as a link. APG's own guidance is that site navigation built from real links uses disclosure navigation; treeview is for tree widgets such as file explorers",
+        "NOT the aria-activedescendant model <CommandPalette> uses: that pattern requires a single focus-holding widget (a combobox input) that keeps DOM focus while a virtual cursor roves, and a docs sidebar has no such input — focus lives on the links themselves",
+        "NO roving tabindex, and therefore no use of createRovingTabindex: roving tabindex means a single tab stop, which is the opposite of this pattern. Every visible link and toggle is its own tab stop, in DOM order",
+        "NO keydown handler of any kind. Enter and Space activate links and buttons natively; adding a handler would be a third keyboard state machine in a codebase that already has two",
+        "Arrow-key movement is OPTIONAL in APG's disclosure navigation pattern and is a deliberate v1 omission, not an oversight — see the keyboard notes above for why",
+        "Renders a <nav> landmark with an always-present accessible name (default 'Docs')",
+        "Entries are REAL <ul>/<li> lists with a nested <ul> per group, and EVERY <ul> carries an explicit role=\"list\" — Safari/VoiceOver strips list semantics from a list-style:none / display:flex list, losing the 'list, N items' announcement that is the reason this is a list at all. axe cannot detect this",
+        "A collapsed group's <ul> is `hidden`, so its links leave both the accessibility tree and the tab order — a keyboard user never tabs into content they cannot see",
+        "Each disclosure button sets aria-expanded and aria-controls pointing at the id of the <ul> it owns",
+        "A pure group's button takes its accessible name from its own visible label text. The icon-only button beside a section landing link has no text, so it carries an explicit aria-label of the form '<Label> submenu'",
+        "The chevron is a decorative <Icon> (aria-hidden), so it never joins a button's accessible name",
+        "aria-current=\"page\" (NOT \"location\") marks the current entry — these links leave the current document, unlike <TableOfContents>'s in-page anchors",
+        "At most one link carries aria-current at a time",
+        "The current entry is never conveyed by colour alone (WCAG 1.4.1): it gains --font-weight-semibold AND a selected-state tint AND an accent rail. The group containing it gains weight as well, and that marker is supplementary — aria-current on the link is the authoritative state",
+        "Links and toggles meet the WCAG 2.5.5 44px floor via --control-min-touch at every container width, not only where a label happens to wrap",
+        "CSS transitions are wrapped in prefers-reduced-motion: no-preference via the a11y motion-safe mixin",
+        "The chevron rotates a half turn (180deg), which has no horizontal component and so needs no RTL mirroring",
+        "Forced colours redraws the guide rail (GrayText) and the current-entry rail and text (Highlight), and restores the focus outline — a11y.focus-ring draws its indicator as a box-shadow over `outline: none`, and forced-colors discards box-shadow without reinstating the suppressed outline (WCAG 2.4.7)",
+        "The empty state is <nav hidden data-empty=\"true\">, which removes a nameless, link-less landmark from the accessibility tree instead of leaving a dead focus stop"
+    ],
+    "ai": {
+        "synonyms": [
+            "docs sidebar",
+            "documentation nav",
+            "docs navigation",
+            "sidebar tree",
+            "nested nav",
+            "collapsible navigation",
+            "section navigation",
+            "left rail",
+            "docs menu",
+            "disclosure navigation"
+        ],
+        "avoid": [
+            "adding a search or filter field to this component — search is <CommandPalette>, and duplicating it here would mean a second index, a second filter and a second set of combobox semantics",
+            "using <TableOfContents> for this job — it links only WITHIN the current document; this component links BETWEEN pages",
+            "reaching for role=\"tree\" / role=\"treeitem\" because the markup is a tree — treeitem on an <a href> destroys the link role and the screen-reader links rotor; APG's guidance for link-based site navigation is disclosure navigation",
+            "adding arrow-key navigation 'for completeness' — it is optional in the pattern, and this component deliberately adds no keyboard state machine",
+            "writing href values with a trailing slash — matching is exact string equality against the router path",
+            "mounting two sidebars with the default storageKey — they will overwrite each other's collapse state; give each its own key or pass null"
+        ],
+        "patterns": [
+            "Flat list: DocsSidebar({ items: [{ label: 'Intro', href: '/docs' }, { label: 'API', href: '/docs/api' }] })",
+            "Grouped: a group entry with `items` and no `href` renders a disclosure button whose own text is its accessible name",
+            "Section landing page: a group entry with BOTH `href` and `items` renders a link plus a separate icon-only disclosure button",
+            "Titled: DocsSidebar({ title: 'Guides', titleLevel: 2, items })",
+            "No persistence: DocsSidebar({ items, storageKey: null })",
+            "Two on a page: give each a distinct storageKey, e.g. 'docs:guides' and 'docs:api'"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Transparent — the sidebar sits on whatever surface the docs layout gives it and adds no fill of its own. The only painted areas are the hover tint and the current entry's selected-state tint, both --color-primary washes at design-system state opacities. Text is --color-text-muted at rest so the tree recedes behind the article it navigates, stepping up to --color-text on hover and on the group containing the current page.",
+        "depth": "Flat. No shadow, no elevation. A docs sidebar is a map beside the content, not a panel floating over it.",
+        "borders": "One border, used as a guide rail: a --border-width-thin inline-start edge on NESTED lists only. The root list has none — a spine down the whole component would imply the top level is itself some group's contents. The current entry's accent rail is a separate --border-width-medium overlay pulled out over that hairline, so activation replaces a colour rather than changing a box size and nothing reflows as the reader navigates.",
+        "interactivity": "Two control types and nothing else: links navigate, disclosure buttons expand. Hover raises the text colour and adds the primary tint on both; :focus-visible surfaces the design-system focus ring on both. The current entry is the only persistent state, tripled up (weight + tint + rail) so it never depends on colour.",
+        "motion": "Colour, background and a 180deg chevron rotation, all inside prefers-reduced-motion: no-preference. Expansion itself is NOT animated — a height transition on a list of unknown depth either needs a measured max-height (which clips) or `interpolate-size` (not yet broadly available), and a half-animated disclosure reads worse than an instant one.",
+        "darkMode": "Nothing to do: every value is a --color-* token, so the muted/rest/current relationship inverts with the theme. The forced-colours block is the separate case — there the rails and the current entry are redrawn with GrayText/Highlight because author colours are discarded outright.",
+        "bestPractices": "Reach for it whenever documentation has more than one page. Keep the tree two or three levels deep — a fourth level is a sign the information architecture, not the component, needs work. Give groups explicit `id`s if the labels are likely to be rewritten, so readers keep their collapsed sections across a docs refresh. Leave `defaultOpen` alone unless a group is genuinely reference material the reader rarely wants; opening collapsed hides the navigation the component exists to provide. Pair it with <TableOfContents> on the other side of the article: this one answers 'which page am I on', that one answers 'where in the page am I'. If you want search, add <CommandPalette> to the page header — do not add a field here."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Flat tree",
+            "pithy": "DocsSidebar({ items: [{ label: 'Introduction', href: '/docs' }] })",
+            "assertions": [
+                "renders <nav class='ui-docs-sidebar' aria-label='Docs'>",
+                "the root <ul> carries an explicit role='list'",
+                "each entry is an <a href> inside an <li>"
+            ]
+        },
+        {
+            "id": "groups",
+            "title": "Nested groups",
+            "pithy": "DocsSidebar({ items: [{ label: 'Guides', items: [{ label: 'Install', href: '/docs/install' }] }] })",
+            "assertions": [
+                "the group renders a <button type='button' aria-expanded aria-controls>",
+                "aria-controls resolves to the id of the group's own nested <ul>",
+                "the nested <ul> also carries role='list'",
+                "a collapsed group's <ul> is hidden, so its links are not tabbable"
+            ]
+        },
+        {
+            "id": "landing-page",
+            "title": "Group that is also a link",
+            "pithy": "DocsSidebar({ items: [{ label: 'Guides', href: '/docs/guides', items: [{ label: 'Install', href: '/docs/guides/install' }] }] })",
+            "assertions": [
+                "renders an <a> and a <button> as siblings inside one row",
+                "the icon-only button carries aria-label='Guides submenu'",
+                "the link is navigable and the button toggles, independently"
+            ]
+        },
+        {
+            "id": "active-route",
+            "title": "Active route and force-expand",
+            "pithy": "DocsSidebar({ items })",
+            "assertions": [
+                "the link whose href equals the router path gains aria-current='page'",
+                "at most one link carries aria-current at a time",
+                "every ancestor group of that link is expanded on mount, even when the persisted state says collapsed",
+                "the force-expand is not written back to storage"
+            ]
+        },
+        {
+            "id": "persistence",
+            "title": "Persisted collapse",
+            "pithy": "DocsSidebar({ items, storageKey: 'docs:guides' })",
+            "assertions": [
+                "clicking a disclosure writes { key: boolean } to localStorage under the given key",
+                "a corrupt or non-object payload degrades to defaults instead of throwing",
+                "storageKey: null reads and writes nothing"
+            ]
+        }
+    ]
+}