@ismail-elkorchi/ui-shell 0.1.0 → 0.1.2

package/README.md

@@ -1,113 +1,185 @@
 # @ismail-elkorchi/ui-shell
 
-Tailwind-friendly shell components (activity bar, sidebars, status bar, and an optional frame layout) for Light DOM layouts. They render Tailwind utility classes, depend on `@ismail-elkorchi/ui-primitives` for controls, and stay framework-agnostic.
-
-## Build & distribution
-
-- `npm run build` emits ESM + `.d.ts` modules into `dist/` for `index/register/router`, layout, activity bar, sidebar, secondary sidebar, and status bar.
-- Tailwind scanning helper ships as `dist/tailwind-source.css`.
-- Published output contains only `dist/` plus this README; TypeScript sources stay in the workspace.
+Token-driven shell components (activity bar, sidebars, status bar, and an optional frame layout) for Light DOM composition. They depend on `@ismail-elkorchi/ui-primitives` for controls, expose slots + parts, and read all visual values from `@ismail-elkorchi/ui-tokens` CSS variables.
 
 ## Layout layer
 
 - Regions: left rail (`activity-bar`), primary sidebar, main content, optional secondary sidebar, and status bar.
 - `uik-shell-layout` stitches the regions together and tags them with `data-region` attributes to keep the layout contract visible in the DOM.
 - Shell components expose only UI surface/state; business logic should live in the host app.
-- **Contract**: Shell components use `ui-primitives` strictly via their public API (attributes/props). They do not rely on Tailwind utility injection to style the internals of primitives (no `class="text-red-500"` on a `uik-button`).
+- **Contract**: Shell components use `ui-primitives` strictly via their public API (attributes/props). Visual styling comes from `--uik-*` custom properties (no framework utility classes).
+
+## Landmarks & labels (Accessibility contract)
+
+- `uik-shell-layout` renders a `role="region"` container; override its label via `aria-label` or `aria-labelledby` on the host.
+- `uik-shell-activity-bar` renders an `<aside>` landmark and forwards `aria-label`/`aria-labelledby` to the internal nav rail; default label is "Activity bar".
+- `uik-shell-sidebar` and `uik-shell-secondary-sidebar` render `<aside>` landmarks; default labels come from the `heading` or fall back to "Sidebar"/"Secondary sidebar".
+- `uik-shell-status-bar` uses `role="status"` with `aria-live="polite"` for status messages.
+- Provide a semantic `<main>` element in the `main-content` slot and label additional landmarks as needed in host markup.
+
+## Focus + roving focus
+
+- Shell navigation surfaces delegate roving focus to primitives (`uik-nav-rail`, `uik-tree-view`) and do not add competing keyboard handlers.
+- Follow the Focus + Roving Focus contract in `@ismail-elkorchi/ui-primitives` when composing activity bars or navigation trees.
+
+## Overlay close semantics
+
+- Overlay-like shells emit close events with `detail.reason` aligned to primitives: `escape | outside | programmatic | toggle`.
+- `uik-shell-secondary-sidebar` captures the previously focused element on open and restores focus on close (unless a `focus-return-target` is provided).
 
 ## Using the components
 
 ```ts
-import {html} from 'lit';
-import '@ismail-elkorchi/ui-primitives/register';
-import '@ismail-elkorchi/ui-shell/register';
-import type {ActivityBarItem} from '@ismail-elkorchi/ui-shell/activity-bar';
+import { html } from "lit";
+import "@ismail-elkorchi/ui-primitives/register";
+import "@ismail-elkorchi/ui-shell/register";
+import type { UikShellActivityBarItem } from "@ismail-elkorchi/ui-shell/activity-bar";
 
-const activityItems: ActivityBarItem[] = [
+const activityItems: UikShellActivityBarItem[] = [
   {
-    id: 'explorer',
-    label: 'Explorer',
-    icon: 'M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z'
+    id: "explorer",
+    label: "Explorer",
+    icon: "M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z",
+  },
+  {
+    id: "search",
+    label: "Search",
+    icon: "M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z",
   },
-  {id: 'search', label: 'Search', icon: 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'}
 ];
 
 html`
-  <uik-shell-layout
-    .activityBar=${html`
-      <uik-shell-activity-bar
-        .items=${activityItems}
-        .activeId=${'explorer'}
-        @activity-select=${(e: CustomEvent<{id: string}>) => console.log(e.detail.id)}>
-      </uik-shell-activity-bar>
-    `}
-    .primarySidebar=${html`
-      <uik-shell-sidebar
-        heading="Explorer"
-        .actions=${html`<uik-button variant="ghost" size="icon">…</uik-button>`}
-        .body=${html`<!-- put your file tree or filters here -->`}>
-      </uik-shell-sidebar>
-    `}
-    .mainContent=${html`<main class="flex-1">Your editor or tabs</main>`}
-    .secondarySidebar=${html`
-      <uik-shell-secondary-sidebar
-        .open=${true}
-        heading="AI Assistant"
-        .body=${html`<p class="text-sm text-muted-foreground">Auxiliary tools live here.</p>`}
-        @secondary-close=${() => console.log('close secondary')}></uik-shell-secondary-sidebar>
-    `}
-    .statusBar=${html`
-      <uik-shell-statusbar message="Ready" tone="info" .meta=${'3 files selected'}></uik-shell-statusbar>
-    `}
-    ?showSecondary=${true}>
+  <uik-shell-layout ?isSecondarySidebarVisible=${true}>
+    <uik-shell-activity-bar
+      slot="activity-bar"
+      .items=${activityItems}
+      .activeId=${"explorer"}
+      @activity-bar-select=${(e: CustomEvent<{ id: string }>) =>
+        console.log(e.detail.id)}
+    >
+    </uik-shell-activity-bar>
+    <uik-shell-sidebar slot="primary-sidebar" heading="Explorer">
+      <uik-button slot="actions" variant="ghost" size="icon">…</uik-button>
+      <div style="font-size: var(--uik-typography-font-size-2);">
+        <!-- put your tree view or navigation here -->
+      </div>
+    </uik-shell-sidebar>
+    <main
+      slot="main-content"
+      style="flex: 1 1 auto; min-height: var(--uik-space-0);"
+    >
+      Your editor or subviews
+    </main>
+    <uik-shell-secondary-sidebar
+      slot="secondary-sidebar"
+      .isOpen=${true}
+      heading="AI Assistant"
+      @secondary-sidebar-close=${() => console.log("close secondary")}
+    >
+      <p
+        style="
+          font-size: var(--uik-typography-font-size-2);
+          color: oklch(var(--uik-text-muted));
+        "
+      >
+        Auxiliary tools live here.
+      </p>
+    </uik-shell-secondary-sidebar>
+    <uik-shell-status-bar
+      slot="status-bar"
+      message="Ready"
+      tone="info"
+      meta="3 files selected"
+    ></uik-shell-status-bar>
   </uik-shell-layout>
 `;
 ```
 
 ### Component notes
 
-- `uik-shell-activity-bar`: accepts `.items` (id/label/icon/path) and emits `activity-select`.
-- `uik-shell-sidebar`: header/heading with `.actions`, `.body`, and optional `.footer`; `paddedBody`/`scrollBody` toggle spacing and scroll.
-- `uik-shell-secondary-sidebar`: controlled via `.open`; emits `secondary-close` when the close button is clicked.
-- `uik-shell-statusbar`: `.message` + `.tone` colorizes the left side; `.meta` renders on the right (string becomes an outline badge).
+- `uik-shell-layout`: named slots `activity-bar`, `primary-sidebar`, `main-content`, `secondary-sidebar`, `status-bar`.
+- `uik-shell-activity-bar`: accepts `.items` (id/label/icon/path) and emits `activity-bar-select`; optional `footer` slot; delegates roving focus to `uik-nav-rail` (set `aria-label` if you need a custom name).
+- `uik-shell-sidebar`: `slot="actions"` for header actions, default slot for body, optional `slot="footer"`; `isBodyPadded`/`isBodyScrollable` toggle spacing + scroll.
+- `uik-shell-secondary-sidebar`: controlled via `.isOpen`; optional `focus-return-target` (selector or element) to restore focus on close; Escape and the close button emit `secondary-sidebar-close` (`detail.reason` is `escape | toggle`).
+- `uik-shell-status-bar`: `.message` + `.tone` colorize the left side; `meta` string (outline badge) or `slot="meta"` for custom content; optional `slot="actions"`.
+- Use `@ismail-elkorchi/ui-primitives/uik-nav` or `@ismail-elkorchi/ui-primitives/uik-tree-view` for sidebar navigation content.
+
+### Custom properties
+
+- Activity bar: `--uik-component-shell-activity-bar-bg`, `--uik-component-shell-activity-bar-fg`, `--uik-component-shell-activity-bar-width`, `--uik-component-shell-activity-bar-item-size`, `--uik-component-shell-activity-bar-item-icon-size`, `--uik-component-shell-activity-bar-item-indicator-bg`, `--uik-component-shell-activity-bar-item-indicator-radius`, `--uik-component-shell-activity-bar-item-indicator-width`.
+- Sidebar: `--uik-component-shell-sidebar-bg`, `--uik-component-shell-sidebar-fg`, `--uik-component-shell-sidebar-width`.
+- Secondary sidebar: `--uik-component-shell-secondary-sidebar-bg`, `--uik-component-shell-secondary-sidebar-width`.
+- Status bar: `--uik-component-shell-status-bar-bg`, `--uik-component-shell-status-bar-fg`, `--uik-component-shell-status-bar-height`.
+- Shared: `--uik-component-shell-divider-color`, `--uik-component-shell-scrollbar-track`, `--uik-component-shell-scrollbar-thumb`.
+
+## Tokens & theming
+
+Load tokens once and set theme/density attributes on a shared container (often `:root`):
+
+```css
+@import "@ismail-elkorchi/ui-tokens/index.css";
+```
+
+```html
+<html data-uik-theme="light" data-uik-density="comfortable">
+  ...
+</html>
+```
 
 ## Routing store
 
-A tiny EventTarget-based router lives in `@ismail-elkorchi/ui-shell/router`. It is framework-light, keeps state in memory (no history), and is meant for desktop flows that only need named views and optional subviews/tabs.
+A tiny EventTarget-based router lives in `@ismail-elkorchi/ui-shell/router`. It is framework-light, keeps state in memory (no history), and is meant for desktop flows that only need named views and optional subviews.
 
 ```ts
-import {createAppShellRouter, APP_SHELL_NAV_EVENT, type AppShellNavigationDetail} from '@ismail-elkorchi/ui-shell/router';
+import {
+  createUikShellRouter,
+  UIK_SHELL_NAVIGATION_EVENT,
+  type UikShellNavigationDetail,
+} from "@ismail-elkorchi/ui-shell/router";
 
 const routes = [
-  {id: 'explorer', label: 'Explorer', subviews: ['code', 'prompt', 'apply'], defaultSubview: 'code'},
-  {id: 'search', label: 'Search'},
-  {id: 'settings', label: 'Settings'}
+  {
+    id: "explorer",
+    label: "Explorer",
+    subviews: ["code", "prompt", "apply"],
+    defaultSubview: "code",
+  },
+  { id: "search", label: "Search" },
+  { id: "settings", label: "Settings" },
 ] as const;
 
-export const shellRouter = createAppShellRouter({routes, initialView: 'explorer', initialSubview: 'code'});
+export const shellRouter = createUikShellRouter({
+  routes,
+  initialView: "explorer",
+  initialSubview: "code",
+});
 
 // React to navigation anywhere in the app
-const unsubscribe = shellRouter.subscribe(({view, subview}) => {
-  console.log('Current location', view, subview);
+const unsubscribe = shellRouter.subscribe(({ view, subview }) => {
+  console.log("Current location", view, subview);
 });
 
 // Wire Lit components through events
 html`
   <uik-shell-activity-bar
-    .items=${routes.map(r => ({id: r.id, label: r.label ?? r.id}))}
+    .items=${routes.map((r) => ({ id: r.id, label: r.label ?? r.id }))}
     .activeId=${shellRouter.current.view}
-    @activity-select=${(e: CustomEvent<{id: string}>) => shellRouter.navigate(e.detail.id)}>
+    @activity-bar-select=${(e: CustomEvent<{ id: string }>) =>
+      shellRouter.navigate(e.detail.id)}
+  >
   </uik-shell-activity-bar>
 
   <editor-area
-    .activeTab=${shellRouter.current.subview ?? 'code'}
-    @tab-change=${(e: CustomEvent<{tab: string}>) => shellRouter.navigate(shellRouter.current.view, e.detail.tab)}>
+    .activeSubview=${shellRouter.current.subview ?? "code"}
+    @subview-change=${(e: CustomEvent<{ subview: string }>) =>
+      shellRouter.navigate(shellRouter.current.view, e.detail.subview)}
+  >
   </editor-area>
 `;
 
 // Listen to the low-level navigation event if you prefer EventTarget
-window.addEventListener(APP_SHELL_NAV_EVENT, (event: Event) => {
-  const detail = (event as CustomEvent<AppShellNavigationDetail>).detail;
+window.addEventListener(UIK_SHELL_NAVIGATION_EVENT, (event: Event) => {
+  const detail = (event as CustomEvent<UikShellNavigationDetail>).detail;
   console.log(detail.from, detail.to, detail.route);
 });
 ```
@@ -115,22 +187,3 @@ window.addEventListener(APP_SHELL_NAV_EVENT, (event: Event) => {
 - Routes are simple `{id, label?, subviews?, defaultSubview?}` objects.
 - `navigate(view, subview?)` resolves subviews per route (keeping the last used subview for that route).
 - `subscribe` immediately fires with the current location and returns an unsubscribe function.
-
-## Tailwind v4 scanning
-
-The package ships Tailwind class strings in TypeScript. Add the source hint before importing Tailwind:
-
-```css
-@import '@ismail-elkorchi/ui-tokens/index.css';
-@import '@ismail-elkorchi/ui-shell/tailwind-source.css'; /* pulls in @source "./**/*.{ts,js}" */
-@source "./**/*.{ts,js,html}";
-@import 'tailwindcss';
-```
-
-Adjust the `@source` path to match the location of your entry CSS. Alternatively, add the line yourself:
-
-```css
-@source "../../node_modules/@ismail-elkorchi/ui-shell/**/*.{ts,js}";
-```
-
-Make sure these appear in the renderer entry CSS so Tailwind keeps the shell utilities during tree-shaking.