@bitforgehq/ui 0.3.1 → 0.3.2

package/ai/REFERENCE.index.json

@@ -36,6 +36,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "Injection token holding the user-facing strings in effect for an injector"
     },
+    {
+      "name": "BF_SIDEBAR_STATE_STORAGE",
+      "slug": "bf_sidebar_state_storage",
+      "kind": "token",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Injection token for the store that keeps the collapsed sidebar between visits"
+    },
     {
       "name": "BF_TAB_BAR",
       "slug": "bf_tab_bar",
@@ -71,6 +78,20 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The four tones of an alert, from neutral information to a danger message"
     },
+    {
+      "name": "BfAppFrameBreakpoint",
+      "slug": "bf-app-frame-breakpoint",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The breakpoint where an app frame switches from its header bar to the sidebar"
+    },
+    {
+      "name": "BfAppFrameContentWidth",
+      "slug": "bf-app-frame-content-width",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The maximum width of an app frame's content column, from medium to full"
+    },
     {
       "name": "BfAutocapitalize",
       "slug": "bf-autocapitalize",
@@ -218,6 +239,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The two description list layouts, divided label-value rows or a grid of tiles"
     },
+    {
+      "name": "BfEmptyStateHeading",
+      "slug": "bf-empty-state-heading",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The heading level of an empty state title, one for a whole page"
+    },
     {
       "name": "BfEmptyStateHeadingLevel",
       "slug": "bf-empty-state-heading-level",
@@ -365,6 +393,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "One choice of a select with its value, its label and a disabled flag"
     },
+    {
+      "name": "BfSidebarStateService",
+      "slug": "bf-sidebar-state-service",
+      "kind": "service",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The sidebar's collapsed state, kept in storage between visits of the app"
+    },
     {
       "name": "BfSize",
       "slug": "bf-size",
@@ -386,6 +421,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The three spinner diameters, from inline text to a page loading state"
     },
+    {
+      "name": "BfStatAppearance",
+      "slug": "bf-stat-appearance",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The three stat surfaces, plain, an outlined card or a sunken tile"
+    },
     {
       "name": "BfStatTrend",
       "slug": "bf-stat-trend",
@@ -470,6 +512,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The direction a sorted table column is in, ascending or descending"
     },
+    {
+      "name": "BfTableStack",
+      "slug": "bf-table-stack",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "When a table stacks its rows into cards: never, when narrow, or under touch"
+    },
     {
       "name": "BfTabLinks",
       "slug": "bf-tab-links",
@@ -519,6 +568,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "Replaces built-in strings for an app or a sub-tree, such as a translation"
     },
+    {
+      "name": "provideBfSidebarState",
+      "slug": "provide-bf-sidebar-state",
+      "kind": "function",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Remembers the collapsed sidebar between visits, for desktop web apps"
+    },
     {
       "name": "BF_DESKTOP_TOAST_DEFAULTS",
       "slug": "bf_desktop_toast_defaults",
@@ -1814,6 +1870,13 @@
       "entryPoint": "@bitforgehq/ui/testing",
       "summary": "Test harness for the select: reads its label and options and picks one"
     },
+    {
+      "name": "BfSidebarToggleHarness",
+      "slug": "bf-sidebar-toggle-harness",
+      "kind": "class",
+      "entryPoint": "@bitforgehq/ui/testing",
+      "summary": "Test harness for a sidebar toggle: reads and flips the collapsed sidebar"
+    },
     {
       "name": "BfSidePanelHarness",
       "slug": "bf-side-panel-harness",

package/ai/REFERENCE.json

@@ -81,6 +81,22 @@
       "since": "0.3.0",
       "signature": "const BF_LABELS: InjectionToken<BfLabels>"
     },
+    {
+      "name": "BF_SIDEBAR_STATE_STORAGE",
+      "slug": "bf_sidebar_state_storage",
+      "kind": "token",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/config/sidebar-state.ts",
+      "summary": "Injection token for the store that keeps the collapsed sidebar between visits",
+      "description": "Where `BfSidebarStateService` keeps whether the sidebar is collapsed (the key\n`bf-sidebar-collapsed`, `'true'` or `'false'`): `localStorage` when it is available, otherwise\nan in-memory map. Provide another store (`sessionStorage`, or an in-memory one in tests) to keep\nit elsewhere.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": [],
+      "since": "0.3.2",
+      "signature": "const BF_SIDEBAR_STATE_STORAGE: InjectionToken<Pick<Storage, \"getItem\" | \"setItem\">>"
+    },
     {
       "name": "BF_TAB_BAR",
       "slug": "bf_tab_bar",
@@ -162,6 +178,40 @@
       "signature": "type BfAlertVariant = 'neutral' | 'success' | 'warning' | 'danger'",
       "values": ["neutral", "success", "warning", "danger"]
     },
+    {
+      "name": "BfAppFrameBreakpoint",
+      "slug": "bf-app-frame-breakpoint",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/app-frame/app-frame.component.ts",
+      "summary": "The breakpoint where an app frame switches from its header bar to the sidebar",
+      "description": "The viewport width from which `bf-app-frame` shows its sidebar column instead of the narrow\nheader bar: Tailwind's `md` (768 px) or `lg` (1024 px).",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-app-frame-component"],
+      "since": "0.3.2",
+      "signature": "type BfAppFrameBreakpoint = 'md' | 'lg'",
+      "values": ["md", "lg"]
+    },
+    {
+      "name": "BfAppFrameContentWidth",
+      "slug": "bf-app-frame-content-width",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/app-frame/app-frame.component.ts",
+      "summary": "The maximum width of an app frame's content column, from medium to full",
+      "description": "The maximum width of `bf-app-frame`'s content column: `md` 48rem, `lg` 64rem, `xl` 80rem, or\n`full` for no limit.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-app-frame-component"],
+      "since": "0.3.2",
+      "signature": "type BfAppFrameContentWidth = 'md' | 'lg' | 'xl' | 'full'",
+      "values": ["md", "lg", "xl", "full"]
+    },
     {
       "name": "BfAutocapitalize",
       "slug": "bf-autocapitalize",
@@ -586,6 +636,23 @@
       "signature": "type BfDescriptionListLayout = 'rows' | 'grid'",
       "values": ["rows", "grid"]
     },
+    {
+      "name": "BfEmptyStateHeading",
+      "slug": "bf-empty-state-heading",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/empty-state/empty-state.component.ts",
+      "summary": "The heading level of an empty state title, one for a whole page",
+      "description": "The heading level a `bf-empty-state` title takes: a `BfEmptyStateHeadingLevel`, or `1` when the\nempty state is the page itself (a not-found or no-access page). A new type, so `Record`s over\nthe released `BfEmptyStateHeadingLevel` keep compiling.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": ["bf-empty-state-heading-level"],
+      "usedBy": ["bf-empty-state-component"],
+      "since": "0.3.2",
+      "signature": "type BfEmptyStateHeading = BfEmptyStateHeadingLevel | 1",
+      "values": ["2", "3", "1"]
+    },
     {
       "name": "BfEmptyStateHeadingLevel",
       "slug": "bf-empty-state-heading-level",
@@ -598,7 +665,7 @@
       "methods": [],
       "slots": [],
       "references": [],
-      "usedBy": ["bf-empty-state-component"],
+      "usedBy": ["bf-empty-state-heading"],
       "since": "0.3.0",
       "signature": "type BfEmptyStateHeadingLevel = 2 | 3",
       "values": ["2", "3"]
@@ -999,6 +1066,33 @@
           "readonly": true,
           "default": "'Select all rows'"
         },
+        {
+          "name": "tableSortBy",
+          "kind": "property",
+          "type": "string",
+          "required": true,
+          "doc": "The label of a stacked bf-table's sort select.",
+          "readonly": true,
+          "default": "'Sort by'"
+        },
+        {
+          "name": "tableSortAscending",
+          "kind": "property",
+          "type": "(column: string) => string",
+          "required": true,
+          "doc": "A stacked bf-table's sort option for a column in ascending order.",
+          "readonly": true,
+          "default": "(column) => `${column}, ascending`"
+        },
+        {
+          "name": "tableSortDescending",
+          "kind": "property",
+          "type": "(column: string) => string",
+          "required": true,
+          "doc": "A stacked bf-table's sort option for a column in descending order.",
+          "readonly": true,
+          "default": "(column) => `${column}, descending`"
+        },
         {
           "name": "theme",
           "kind": "property",
@@ -1071,6 +1165,33 @@
           "readonly": true,
           "default": "(count) => `${count} new`"
         },
+        {
+          "name": "sidebarCollapse",
+          "kind": "property",
+          "type": "string",
+          "required": true,
+          "doc": "bf-sidebar-toggle's name and tooltip while the sidebar is expanded.",
+          "readonly": true,
+          "default": "'Collapse sidebar'"
+        },
+        {
+          "name": "sidebarExpand",
+          "kind": "property",
+          "type": "string",
+          "required": true,
+          "doc": "bf-sidebar-toggle's name and tooltip while the sidebar is an icon rail.",
+          "readonly": true,
+          "default": "'Expand sidebar'"
+        },
+        {
+          "name": "skipToContent",
+          "kind": "property",
+          "type": "string",
+          "required": true,
+          "doc": "bf-app-frame's skip link, the first stop of the tab order, which moves focus to the content.",
+          "readonly": true,
+          "default": "'Skip to main content'"
+        },
         {
           "name": "pagination",
           "kind": "property",
@@ -1655,6 +1776,30 @@
       "since": "0.1.0",
       "signature": "interface BfSelectOption<T = string>"
     },
+    {
+      "name": "BfSidebarStateService",
+      "slug": "bf-sidebar-state-service",
+      "kind": "service",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/config/sidebar-state.ts",
+      "summary": "The sidebar's collapsed state, kept in storage between visits of the app",
+      "description": "Whether the app's `bf-sidebar` is collapsed to an icon rail, remembered between visits: the app\nbinds the sidebar's `[(collapsed)]` to `sidebarState.collapsed`. With `provideBfSidebarState()`\nevery change is stored in `BF_SIDEBAR_STATE_STORAGE` under `bf-sidebar-collapsed`; without it\nthe signal still holds the state but nothing is written. Storage is read in the browser only, so a\nserver render starts expanded and writes nothing. The widgets never inject it.",
+      "members": [
+        {
+          "name": "collapsed",
+          "kind": "property",
+          "type": "WritableSignal<boolean>",
+          "required": false,
+          "doc": "Whether the sidebar is collapsed: the stored state in the browser, else false. Bind it two-way to `bf-sidebar`'s `collapsed`.",
+          "readonly": true
+        }
+      ],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": [],
+      "since": "0.3.2"
+    },
     {
       "name": "BfSize",
       "slug": "bf-size",
@@ -1692,6 +1837,7 @@
         "bf-segmented-component",
         "bf-segmented-size",
         "bf-select-component",
+        "bf-sidebar-toggle-component",
         "bf-tab-group-component",
         "bf-table-component",
         "bf-textarea-component",
@@ -1738,6 +1884,23 @@
       "signature": "type BfSpinnerSize = 'sm' | 'md' | 'lg'",
       "values": ["sm", "md", "lg"]
     },
+    {
+      "name": "BfStatAppearance",
+      "slug": "bf-stat-appearance",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/stat/stat.component.ts",
+      "summary": "The three stat surfaces, plain, an outlined card or a sunken tile",
+      "description": "The surface of a `bf-stat`, as its `variant` input takes it: a `BfStatVariant` or tile (a\nsunken, borderless tile for a stats row inside a raised card). A new type, so `Record`s over\nthe released `BfStatVariant` keep compiling.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": ["bf-stat-variant"],
+      "usedBy": ["bf-stat-component"],
+      "since": "0.3.2",
+      "signature": "type BfStatAppearance = BfStatVariant | 'tile'",
+      "values": ["plain", "card", "tile"]
+    },
     {
       "name": "BfStatTrend",
       "slug": "bf-stat-trend",
@@ -1784,7 +1947,7 @@
       "methods": [],
       "slots": [],
       "references": [],
-      "usedBy": ["bf-stat-component"],
+      "usedBy": ["bf-stat-appearance"],
       "since": "0.3.1",
       "signature": "type BfStatVariant = 'plain' | 'card'",
       "values": ["plain", "card"]
@@ -2144,6 +2307,23 @@
       "signature": "type BfTableSortDirection = 'ascending' | 'descending'",
       "values": ["ascending", "descending"]
     },
+    {
+      "name": "BfTableStack",
+      "slug": "bf-table-stack",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/table/table.component.ts",
+      "summary": "When a table stacks its rows into cards: never, when narrow, or under touch",
+      "description": "When a `bf-table` renders each row as a card of label/value pairs: `never` (the default),\n`narrow` while the table is narrower than 36rem (a container query), or `coarse` under a coarse\npointer at any width.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-table-component"],
+      "since": "0.3.2",
+      "signature": "type BfTableStack = 'never' | 'narrow' | 'coarse'",
+      "values": ["never", "narrow", "coarse"]
+    },
     {
       "name": "BfTabLinks",
       "slug": "bf-tab-links",
@@ -2419,7 +2599,7 @@
       "entryPoint": "@bitforgehq/ui",
       "file": "src/config/labels.ts",
       "summary": "Replaces built-in strings for an app or a sub-tree, such as a translation",
-      "description": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `theme`,\n`themeSystem`, `themeLight`, `themeDark`, `breadcrumb`, `breadcrumbExpand`, `navigation`,\n`navBadge`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`.",
+      "description": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`.",
       "members": [],
       "methods": [
         {
@@ -2434,7 +2614,7 @@
             }
           ],
           "returns": "Provider",
-          "doc": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `theme`,\n`themeSystem`, `themeLight`, `themeDark`, `breadcrumb`, `breadcrumbExpand`, `navigation`,\n`navBadge`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`."
+          "doc": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`."
         }
       ],
       "slots": [],
@@ -2443,6 +2623,30 @@
       "since": "0.3.0",
       "signature": "function provideBfLabels(overrides: BfLabelsOverrides): Provider"
     },
+    {
+      "name": "provideBfSidebarState",
+      "slug": "provide-bf-sidebar-state",
+      "kind": "function",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/config/sidebar-state.ts",
+      "summary": "Remembers the collapsed sidebar between visits, for desktop web apps",
+      "description": "Lets `BfSidebarStateService` remember the collapsed sidebar: it stores every change of its\n`collapsed` signal (key `bf-sidebar-collapsed`, `localStorage` in the browser), so the app opens\nwith the sidebar as the user left it. Add it to `ApplicationConfig.providers` and bind the\nsidebar's `[(collapsed)]` to `sidebarState.collapsed`.",
+      "members": [],
+      "methods": [
+        {
+          "name": "provideBfSidebarState",
+          "signature": "provideBfSidebarState(): EnvironmentProviders",
+          "params": [],
+          "returns": "EnvironmentProviders",
+          "doc": "Lets `BfSidebarStateService` remember the collapsed sidebar: it stores every change of its\n`collapsed` signal (key `bf-sidebar-collapsed`, `localStorage` in the browser), so the app opens\nwith the sidebar as the user left it. Add it to `ApplicationConfig.providers` and bind the\nsidebar's `[(collapsed)]` to `sidebarState.collapsed`."
+        }
+      ],
+      "slots": [],
+      "references": [],
+      "usedBy": [],
+      "since": "0.3.2",
+      "signature": "function provideBfSidebarState(): EnvironmentProviders"
+    },
     {
       "name": "BF_DESKTOP_TOAST_DEFAULTS",
       "slug": "bf_desktop_toast_defaults",
@@ -9428,6 +9632,44 @@
       "since": "0.3.0",
       "signature": "class BfSelectHarness extends ComponentHarness"
     },
+    {
+      "name": "BfSidebarToggleHarness",
+      "slug": "bf-sidebar-toggle-harness",
+      "kind": "class",
+      "entryPoint": "@bitforgehq/ui/testing",
+      "file": "testing/harnesses/sidebar-toggle.harness.ts",
+      "summary": "Test harness for a sidebar toggle: reads and flips the collapsed sidebar",
+      "description": "Harness for `bf-sidebar-toggle`, the button that collapses a `bf-sidebar` to an icon rail. Its\n`label` filter matches the button's name (\"Collapse sidebar\" or \"Expand sidebar\").",
+      "members": [],
+      "methods": [
+        {
+          "name": "getLabel",
+          "signature": "getLabel(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The button's name, which says what the next press does."
+        },
+        {
+          "name": "isExpanded",
+          "signature": "isExpanded(): Promise<boolean>",
+          "params": [],
+          "returns": "Promise<boolean>",
+          "doc": "Whether the sidebar is at full width (`aria-expanded`)."
+        },
+        {
+          "name": "toggle",
+          "signature": "toggle(): Promise<void>",
+          "params": [],
+          "returns": "Promise<void>",
+          "doc": "Flips the sidebar with a click."
+        }
+      ],
+      "slots": [],
+      "references": [],
+      "usedBy": [],
+      "since": "0.3.2",
+      "signature": "class BfSidebarToggleHarness extends ComponentHarness"
+    },
     {
       "name": "BfSidePanelHarness",
       "slug": "bf-side-panel-harness",
@@ -9532,7 +9774,7 @@
       "entryPoint": "@bitforgehq/ui/testing",
       "file": "testing/harnesses/table.harness.ts",
       "summary": "Test harness for the data table: reads rows and cells, sorts and selects rows",
-      "description": "Harness for `bf-table`. It works by column header text and row position, so a test never needs\nthe column keys or the row keys (except `getSort()`, which returns the column's `key`, as the\n`sort` model holds it).",
+      "description": "Harness for `bf-table`. It works by column header text and row position, so a test never needs\nthe column keys or the row keys (except `getSort()`, which returns the column's `key`, as the\n`sort` model holds it). It reads and drives a stacked table (`stack`) the same way.",
       "members": [],
       "methods": [
         {

package/ai/UI_GUIDE.md

@@ -117,7 +117,12 @@ the widgets style their native controls themselves.
 Optional per-app overrides go after the import. A brand colour is a set: override
 `--color-primary` together with `--color-primary-text` (primary as text, ≥ 4.5:1 on `bg` and
 `surface`) and the rest of the `--color-primary-*` tokens, in `@theme` and in `.dark`; the docs
-site's theme configurator derives the whole contrast-checked set from one colour.
+site's theme configurator derives the whole contrast-checked set from one colour. From a
+terminal, `bunx bf-ui theme '<hex>' [--dark '<hex>']` prints the set (`primary`, its hover,
+pressed, soft and strong steps, `on-primary`, `primary-text`, `selected`, `ring`) as a `@theme`
+and a `.dark` block with each contrast pair's ratio, and exits 1 naming the pairs below their
+minimum and a shade that passes; paste its output, never hand-pick the steps. Example (the
+Meadow Sage green): `bunx bf-ui theme '#238652' --dark '#5cc48a'`.
 `--radius-control` (`9999px`, pills) reshapes buttons, chips, badges, segmented, the tab bar, the
 action bar and toggles at once:
 
@@ -138,16 +143,17 @@ Render library components only in the browser, for example in a `@defer` block o
 route. Support will be decided before 1.0.
 
 The one server-side check is a render smoke, not a support test: the library repository's
-`tools/ssr-smoke.ts` renders 42 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`tools/ssr-smoke.ts` renders 43 fixtures with `renderApplication()` (every root widget, `bf-icon`,
 `bf-number-input`, a `/charts` line chart, a `/mobile` page with `provideBfShell()`, `bf-page`,
 `bf-header` and `bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay`
-dialog), and all of them render without an error. 27 of them render identically twice. The other 15
+dialog), and all of them render without an error. 27 of them render identically twice. The other 16
 number their ids differently on every render, from a module-level counter, so they could not
-hydrate: `bf-calendar`, `bf-checkbox`, `bf-input`, `bf-radio-group`, `bf-segmented`, `bf-select`,
-`bf-sidebar`, `bf-tab-group`, `bf-table`, `bf-textarea`, `bf-theme-switch`, `bf-toggle`,
-`bf-line-chart`, `bf-number-input` and the `/overlay` dialog. Hydration itself is still not
-supported or tested, and more stands in its way: `/mobile` writes to `<html>` and adds a keyboard
-probe to `<body>`, and an `/overlay` dialog renders outside the app root and marks it inert.
+hydrate: `bf-app-frame`, `bf-calendar`, `bf-checkbox`, `bf-input`, `bf-radio-group`, `bf-segmented`,
+`bf-select`, `bf-sidebar`, `bf-tab-group`, `bf-table`, `bf-textarea`, `bf-theme-switch`,
+`bf-toggle`, `bf-line-chart`, `bf-number-input` and the `/overlay` dialog. Hydration itself is still
+not supported or tested, and more stands in its way: `/mobile` writes to `<html>` and adds a
+keyboard probe to `<body>`, and an `/overlay` dialog renders outside the app root and marks it
+inert.
 
 ## Keeping this guide in sync
 
@@ -335,8 +341,19 @@ protected readonly colorScheme = inject(BfColorSchemeService);
 `bf-tabs`, `bf-back-button` and `bf-header` are Capacitor shell parts. A desktop web app (no
 `provideBfShell()`) uses their desktop counterparts from `@bitforgehq/ui`:
 
-- **Navigation:** `bf-sidebar` (groups in `bf-nav-group`, `[(collapsed)]` for an icon rail; the
-  app owns the toggle button) or `bf-top-nav` for a few sections, holding
+- **App frame:** wrap the whole app in `<bf-app-frame>` (never build the frame by hand): the
+  `bf-sidebar` in `bfSlot="sidebar"` (sticky, full height, from `md` up), and below the
+  breakpoint a header bar with `bfSlot="brand"`, `bfSlot="menu"` (a `bf-menu-button` of
+  `a[bfMenuItem]` links from the same destinations array) and `bfSlot="actions"` (the theme
+  menu); the router outlet is the content. It brings the skip link and the focusable main
+  landmark; `breakpoint` and `contentWidth` adjust it. Desktop only: never inside
+  `provideBfShell()`.
+- **Sidebar collapse:** `<bf-sidebar-toggle>` (`/overlay`, icons in `bfSlot="collapse-icon"` and
+  `bfSlot="expand-icon"`) in the sidebar footer beside the icon-only theme menu; with
+  `provideBfSidebarState()` bind `[(collapsed)]="sidebarState.collapsed"`
+  (`BfSidebarStateService`) so the choice is remembered.
+- **Navigation:** `bf-sidebar` (groups in `bf-nav-group`, `[(collapsed)]` for an icon rail) or
+  `bf-top-nav` for a few sections, holding
   `<a bfNavItem routerLink="…" routerLinkActive ariaCurrentWhenActive="page">` links with an icon
   in `bfSlot="icon"` and an optional `[badge]` count. The router sets `aria-current="page"` and
   the item shows it. Drive the sidebar, a below-`md` `bf-menu-button` of `a[bfMenuItem]` links and,
@@ -354,8 +371,9 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   controls default to `sm`, and `status` is a polite live region for the result count.
 - **Table:** `<bf-table [rows] [columns] [(sort)] selectable [(selection)]>` with
   `ng-template[bfTableCell]` for rich cells and `bfSlot="empty"` for the empty state; the app
-  sorts the rows in a `computed()`, and a selection shows a `bf-action-bar`. Below `md` or on a
-  coarse pointer render the same rows as `bf-list-item`s.
+  sorts the rows in a `computed()`, and a selection shows a `bf-action-bar`. `stack="narrow"`
+  (below 36rem of its own width) or `stack="coarse"` turns each row into a label/value tile with
+  a sort and select bar; in the Capacitor shell use `bf-list-item` rows instead.
 - **Details:** `bf-description-list` of `div[bfDescriptionItem]` label/value pairs, and `bf-stat`
   figure tiles in a grid; both work in both shells.
 - **Cards in a grid:** the grid stretches each `bf-card` and its `bfSlot="footer"` sits on the
@@ -384,6 +402,12 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   `bf-sparkline` inside a `bf-chart-card` (title, period slot, loading, empty and error states),
   themed by the `chart-1`…`chart-8` tokens. Every chart takes a `label` and offers its data as a
   table.
+- **Surfaces:** one surface style per level. A raised `bf-card` holds sunken tiles
+  (`bf-stat variant="tile"`), never an outlined surface (`variant="card"` or a `flat` card) inside
+  a raised one; next to raised cards on a dashboard, use raised cards.
+- **Empty pages:** a 404, "no access" or "nothing here yet" page is a `bf-empty-state` with
+  `headingLevel` 1, centred in the content area, with the main action and an optional link.
+- **Toolbar on a phone:** `bf-toolbar` keeps its status and actions together on the last row.
 
 ## Overlays (`@bitforgehq/ui/overlay`)
 
@@ -1228,27 +1252,29 @@ notes.
 
 ### Navigation
 
-| Component              | Entry point             | Purpose                                                                                     |
-| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
-| `bf-back-button`       | `@bitforgehq/ui/mobile` | Header back button that pops the page stack or falls back to a default route                |
-| `bf-breadcrumb`        | `@bitforgehq/ui`        | Desktop breadcrumb trail of links to the current page, with optional collapsing             |
-| `li[bfBreadcrumbItem]` | `@bitforgehq/ui`        | One level of a breadcrumb trail: a link, or the current page as text                        |
-| `bf-content`           | `@bitforgehq/ui/mobile` | Page's single scroll container that keeps focused fields clear of the soft keyboard         |
-| `bf-header`            | `@bitforgehq/ui/mobile` | Page header toolbar with a large title that collapses into the toolbar on scroll            |
-| `bf-nav-group`         | `@bitforgehq/ui`        | A titled group of sidebar links with a small heading that names it                          |
-| `a[bfNavItem]`         | `@bitforgehq/ui`        | Navigation link for a sidebar or top nav, with icon, label and count                        |
-| `bf-page`              | `@bitforgehq/ui/mobile` | Frame for one stacked mobile screen that supplies lifecycle events and shared page state    |
-| `bf-page-header`       | `@bitforgehq/ui`        | Desktop page header with breadcrumb, title, subtitle, badges and a row of actions           |
-| `bf-pagination`        | `@bitforgehq/ui`        | Previous, next and numbered page buttons for a long list or table                           |
-| `bf-refresher`         | `@bitforgehq/ui/mobile` | Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull |
-| `bf-sidebar`           | `@bitforgehq/ui`        | Vertical app navigation with brand, grouped links, footer and an icon rail mode             |
-| `bf-stack-outlet`      | `@bitforgehq/ui/mobile` | Router outlet keeping a live page stack with slide transitions and iOS swipe back           |
-| `bf-tab`               | `@bitforgehq/ui`        | One tab bar destination with an icon, a label and an optional count badge                   |
-| `bf-tab-bar`           | `@bitforgehq/ui`        | Floating pill tab bar for mobile apps with arrow-key selection and count badges             |
-| `bf-tab-group`         | `@bitforgehq/ui`        | In-page tabs that switch between content panels, with keyboard navigation and badges        |
-| `bf-tab-panel`         | `@bitforgehq/ui`        | One tab of a tab group with its label, badge, icon and lazy content                         |
-| `bf-tabs`              | `@bitforgehq/ui/mobile` | Tabs page with one navigation stack per tab, wiring the tab bar to the router               |
-| `bf-top-nav`           | `@bitforgehq/ui`        | Horizontal app navigation, a wrapping row of links for apps with few sections               |
+| Component              | Entry point              | Purpose                                                                                     |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
+| `bf-app-frame`         | `@bitforgehq/ui`         | Desktop app frame with skip link, sticky sidebar, narrow header and main content            |
+| `bf-back-button`       | `@bitforgehq/ui/mobile`  | Header back button that pops the page stack or falls back to a default route                |
+| `bf-breadcrumb`        | `@bitforgehq/ui`         | Desktop breadcrumb trail of links to the current page, with optional collapsing             |
+| `li[bfBreadcrumbItem]` | `@bitforgehq/ui`         | One level of a breadcrumb trail: a link, or the current page as text                        |
+| `bf-content`           | `@bitforgehq/ui/mobile`  | Page's single scroll container that keeps focused fields clear of the soft keyboard         |
+| `bf-header`            | `@bitforgehq/ui/mobile`  | Page header toolbar with a large title that collapses into the toolbar on scroll            |
+| `bf-nav-group`         | `@bitforgehq/ui`         | A titled group of sidebar links with a small heading that names it                          |
+| `a[bfNavItem]`         | `@bitforgehq/ui`         | Navigation link for a sidebar or top nav, with icon, label and count                        |
+| `bf-page`              | `@bitforgehq/ui/mobile`  | Frame for one stacked mobile screen that supplies lifecycle events and shared page state    |
+| `bf-page-header`       | `@bitforgehq/ui`         | Desktop page header with breadcrumb, title, subtitle, badges and a row of actions           |
+| `bf-pagination`        | `@bitforgehq/ui`         | Previous, next and numbered page buttons for a long list or table                           |
+| `bf-refresher`         | `@bitforgehq/ui/mobile`  | Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull |
+| `bf-sidebar`           | `@bitforgehq/ui`         | Vertical app navigation with brand, grouped links, footer and an icon rail mode             |
+| `bf-sidebar-toggle`    | `@bitforgehq/ui/overlay` | Icon button inside a sidebar that collapses it to an icon rail and back                     |
+| `bf-stack-outlet`      | `@bitforgehq/ui/mobile`  | Router outlet keeping a live page stack with slide transitions and iOS swipe back           |
+| `bf-tab`               | `@bitforgehq/ui`         | One tab bar destination with an icon, a label and an optional count badge                   |
+| `bf-tab-bar`           | `@bitforgehq/ui`         | Floating pill tab bar for mobile apps with arrow-key selection and count badges             |
+| `bf-tab-group`         | `@bitforgehq/ui`         | In-page tabs that switch between content panels, with keyboard navigation and badges        |
+| `bf-tab-panel`         | `@bitforgehq/ui`         | One tab of a tab group with its label, badge, icon and lazy content                         |
+| `bf-tabs`              | `@bitforgehq/ui/mobile`  | Tabs page with one navigation stack per tab, wiring the tab bar to the router               |
+| `bf-top-nav`           | `@bitforgehq/ui`         | Horizontal app navigation, a wrapping row of links for apps with few sections               |
 
 ### Overlays