@apliteni/apliteni-ui 0.49.1 → 0.50.0

package/guidelines/text-length.md

@@ -0,0 +1,53 @@
+# Text length
+
+## Keep controls short
+
+<!-- rule: short-controls -->
+
+**Rule:** Labels, buttons, badges and status text name the field, action or state in a few words.
+
+**Do:** “Save invoice.”
+
+**Don't:** “Click here to save your invoice.”
+
+## Explain data in captions
+
+<!-- rule: useful-captions -->
+
+**Rule:** Use one sentence for needed units, dates or limits.
+
+**Do:** “March revenue in EUR, excluding refunds.”
+
+**Don't:** “An overview of your revenue.”
+
+## Use introductions only when needed
+
+<!-- rule: useful-introductions -->
+
+**Rule:** Add a short introduction only for a purpose or step the title and controls leave unclear.
+
+**Do:** “Upload a CSV with invoice numbers, dates and amounts.”
+
+**Don't:** “Manage your invoices here.”
+
+## Explain consequences in callouts
+
+<!-- rule: useful-callouts -->
+
+**Rule:** Explain a consequence or next step in one or two sentences.
+
+**Do:** “Deleting this workspace deletes its reports. Export them first.”
+
+**Don't:** “Think carefully before proceeding.”
+
+**Except:** Keep needed safety, consent and legal details visible, however long. Link to optional background.
+
+## Cut filler
+
+<!-- rule: remove-filler -->
+
+**Rule:** Cut text readers can decide and finish without.
+
+**Do:** “Exports include only filtered rows.”
+
+**Don't:** “Export quickly and easily.”

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.49.1",
+  "version": "0.50.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -433,3 +433,20 @@ function SaveButton() {
 
 <Toast><SaveButton /></Toast>
 ```
+
+## AppShell
+
+AppShell includes the kit’s rail and top band. Pass the current router pathname so the longest matching section path becomes active. Spread the props from `renderLink` onto your router link. The rail’s folded state is saved in a shared cookie. On phones, the bar shows up to four sections. If there are more, it shows three sections and a More sheet. Provide no more than one primary page action. The palette defaults to section links; pass `palette` to add custom commands. Import both the kit CSS and React CSS.
+
+```tsx
+<AppShell
+  pathname={location.pathname}
+  sections={[{ href: '/reports', label: 'Reports', icon: 'chart' }]}
+  title="Reports"
+  account={{ name: 'Demo User', email: 'demo@example.com' }}
+  onSignOut={signOut}
+  renderLink={(section, { href, ...props }) => <Link to={section.href} {...props} />}
+>
+  <Reports />
+</AppShell>
+```

package/react/dist/index.css

@@ -525,3 +525,71 @@
 .rx-toast-stack > .ui-toast {
   pointer-events: auto;
 }
+
+/* src/AppShell.css */
+.ui-react-app__bottom {
+  display: none;
+}
+.ui-react-app__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-3);
+  margin-bottom: var(--space-5);
+}
+.ui-react-app .ui-app__brand .ui-react-app__mark {
+  display: inline-flex;
+  opacity: 1;
+}
+.ui-react-app__bottom .ui-nav__item {
+  min-height: 48px;
+}
+@media (max-width: 560px) {
+  .ui-react-app {
+    display: block;
+  }
+  .ui-react-app > .ui-app__rail {
+    display: none;
+  }
+  .ui-react-app .ui-app__main {
+    padding-bottom: calc(96px + env(safe-area-inset-bottom));
+  }
+  .ui-react-app .ui-app__bar {
+    padding-inline: var(--space-4);
+  }
+  .ui-react-app .ui-app__search {
+    min-width: 0;
+  }
+  .ui-react-app .ui-app__search kbd {
+    display: none;
+  }
+  .ui-react-app__bottom {
+    display: block;
+    position: fixed;
+    inset: auto 0 0;
+    z-index: var(--z-sticky);
+    padding: var(--space-2) var(--space-2) calc(var(--space-2) + env(safe-area-inset-bottom));
+    background: var(--bg);
+    border-top: 1px solid var(--border);
+  }
+  .ui-react-app__bottom .ui-nav__list {
+    display: flex;
+    flex-direction: row;
+  }
+  .ui-react-app__bottom li {
+    flex: 1;
+    min-width: 0;
+  }
+  .ui-react-app__bottom .ui-nav__item {
+    justify-content: center;
+    flex-direction: column;
+    gap: var(--space-1);
+    padding-inline: var(--space-1);
+  }
+  .ui-react-app__bottom .ui-nav__label {
+    flex: none;
+    font-size: var(--text-xs);
+  }
+  .ui-react-app__bottom .ui-nav__badge {
+    display: none;
+  }
+}

package/react/dist/index.d.ts

@@ -550,7 +550,43 @@ type ToastProps = {
 declare function useToast(): (notice: ToastNotice) => void;
 declare function Toast({ children }: ToastProps): react.JSX.Element;
 
+type AppShellSection = {
+    href: string;
+    label: string;
+    icon: string;
+    count?: number;
+};
+type AppShellProps = {
+    sections: AppShellSection[];
+    /** Current router pathname; the longest matching section wins. */
+    pathname: string;
+    title: string;
+    children?: ReactNode;
+    word?: string;
+    brand?: ReactNode;
+    brandHref?: string;
+    width?: 'centered' | 'wide';
+    back?: {
+        href: string;
+        label: string;
+    };
+    lede?: string;
+    actions?: ReactNode;
+    bandControl?: ReactNode;
+    account: {
+        name: string;
+        email: string;
+    };
+    onSignOut: () => void;
+    /** Server-read fold preference. The browser restores the shared rail cookie. */
+    defaultCollapsed?: boolean;
+    palette?: Omit<CommandPaletteProps, 'open' | 'onClose'>;
+    /** Spread linkProps onto the router link, including children and onClick. */
+    renderLink?: (section: AppShellSection, linkProps: ComponentPropsWithoutRef<'a'>) => ReactNode;
+};
+declare function AppShell({ sections, pathname, title, children, word, brand, brandHref, width, back, lede, actions, bandControl, account, onSignOut, defaultCollapsed, palette, renderLink }: AppShellProps): react.JSX.Element;
+
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, RowIdentity, type RowIdentityProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, Timeline, type TimelineEvent, type TimelineProps, Toast, type ToastNotice, type ToastProps, sortTableRows, useToast };
+export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, RowIdentity, type RowIdentityProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, Timeline, type TimelineEvent, type TimelineProps, Toast, type ToastNotice, type ToastProps, sortTableRows, useToast };

package/react/dist/index.js

@@ -2152,10 +2152,171 @@ function Toast({ children }) {
   ] });
 }
 
+// src/AppShell.tsx
+import { useEffect as useEffect9, useId as useId9, useState as useState9 } from "react";
+import { applyTheme, paletteHotkey, prism, railCollapsed, themeIcon, themeName } from "@apliteni/apliteni-ui";
+import { Fragment as Fragment7, jsx as jsx25, jsxs as jsxs21 } from "react/jsx-runtime";
+var path = (value) => value.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
+function AppShell({
+  sections,
+  pathname,
+  title,
+  children,
+  word = "apliteni-ui",
+  brand,
+  brandHref = "/",
+  width = "centered",
+  back,
+  lede,
+  actions,
+  bandControl,
+  account,
+  onSignOut,
+  defaultCollapsed = false,
+  palette,
+  renderLink
+}) {
+  const uid = useId9();
+  const [collapsed, setCollapsed] = useState9(defaultCollapsed);
+  const [search, setSearch] = useState9(false);
+  const [more, setMore] = useState9(false);
+  const [theme, setTheme] = useState9("dark");
+  const current = path(pathname);
+  const active = sections.filter((section) => current === path(section.href) || path(section.href) !== "/" && current.startsWith(`${path(section.href)}/`)).sort((a, b) => path(b.href).length - path(a.href).length)[0];
+  useEffect9(() => {
+    setCollapsed(railCollapsed() ?? defaultCollapsed);
+  }, [defaultCollapsed]);
+  useEffect9(() => {
+    setMore(false);
+    setSearch(false);
+  }, [pathname]);
+  useEffect9(() => {
+    const root = document.documentElement;
+    const sync2 = () => setTheme(root.getAttribute("data-theme") === "light" ? "light" : "dark");
+    sync2();
+    const observer = new MutationObserver(sync2);
+    observer.observe(root, { attributes: true, attributeFilter: ["data-theme"] });
+    return () => observer.disconnect();
+  }, []);
+  useEffect9(() => {
+    const hotkey = (event) => {
+      if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey || event.key.toLowerCase() !== "k") return;
+      const target = event.target;
+      if (target?.closest?.('input, textarea, select, [contenteditable]:not([contenteditable="false"]), [role="dialog"]')) return;
+      event.preventDefault();
+      setSearch(true);
+    };
+    document.addEventListener("keydown", hotkey);
+    return () => document.removeEventListener("keydown", hotkey);
+  }, []);
+  const fold = () => {
+    const next = !collapsed;
+    setCollapsed(next);
+    try {
+      document.cookie = `apliteni-ui-rail=${next ? "collapsed" : "expanded"}; Max-Age=31536000; Path=/; SameSite=Lax`;
+    } catch {
+    }
+  };
+  const links = (items) => items.map((section) => {
+    const linkProps = {
+      href: section.href,
+      className: `ui-nav__item${section === active ? " is-active" : ""}`,
+      "aria-current": section === active ? "page" : void 0,
+      "aria-label": `${section.label}${section.count == null ? "" : ` ${section.count}`}`,
+      onClick: (event) => {
+        if (!event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey) setMore(false);
+      },
+      children: /* @__PURE__ */ jsxs21(Fragment7, { children: [
+        /* @__PURE__ */ jsx25("span", { className: "ui-nav__ic", children: /* @__PURE__ */ jsx25(Icon, { name: section.icon }) }),
+        /* @__PURE__ */ jsx25("span", { className: "ui-nav__label", children: section.label }),
+        section.count != null && /* @__PURE__ */ jsx25("span", { className: "ui-nav__badge", children: section.count })
+      ] })
+    };
+    return /* @__PURE__ */ jsx25("li", { children: renderLink ? renderLink(section, linkProps) : /* @__PURE__ */ jsx25("a", { ...linkProps }) }, section.href);
+  });
+  const foldLabel = collapsed ? "Expand sidebar" : "Collapse sidebar";
+  const visible = sections.length > 4 ? sections.slice(0, 3) : sections;
+  const remaining = sections.slice(visible.length);
+  const initials = account.name.trim().split(/\s+/).map((part) => part[0]).slice(0, 2).join("");
+  return /* @__PURE__ */ jsxs21("div", { className: `ui-app ui-app--topbar ui-react-app${collapsed ? " is-collapsed" : ""}`, children: [
+    /* @__PURE__ */ jsxs21("div", { className: "ui-app__rail", children: [
+      /* @__PURE__ */ jsx25("div", { className: "ui-app__head", children: /* @__PURE__ */ jsxs21("a", { className: "ui-app__brand", href: brandHref, "aria-label": word, children: [
+        brand ?? /* @__PURE__ */ jsx25("i", { "aria-hidden": "true", className: "ui-react-app__mark", dangerouslySetInnerHTML: { __html: prism(uid, 24) } }),
+        /* @__PURE__ */ jsx25("span", { children: word })
+      ] }) }),
+      /* @__PURE__ */ jsx25("nav", { className: "ui-nav ui-nav--side", "aria-label": "Sections", children: /* @__PURE__ */ jsx25("ul", { className: "ui-nav__list", children: links(sections) }) }),
+      /* @__PURE__ */ jsx25("div", { className: "ui-app__foot", children: /* @__PURE__ */ jsx25("div", { className: "ui-app__fold-row", children: /* @__PURE__ */ jsxs21("button", { type: "button", className: "ui-nav__item ui-app__fold", "aria-expanded": !collapsed, "aria-label": foldLabel, onClick: fold, children: [
+        /* @__PURE__ */ jsx25("span", { className: "ui-nav__ic", children: /* @__PURE__ */ jsxs21("svg", { className: "ui-icon", viewBox: "0 0 24 24", "aria-hidden": "true", children: [
+          /* @__PURE__ */ jsx25("rect", { x: "3", y: "3", width: "18", height: "18", rx: "2" }),
+          /* @__PURE__ */ jsx25("path", { className: "ui-app__fold-seam", d: "M9 3v18" })
+        ] }) }),
+        /* @__PURE__ */ jsx25("span", { className: "ui-nav__label", children: foldLabel })
+      ] }) }) })
+    ] }),
+    /* @__PURE__ */ jsxs21("div", { className: "ui-app__well", children: [
+      /* @__PURE__ */ jsxs21("header", { className: "ui-app__bar", children: [
+        /* @__PURE__ */ jsxs21("button", { type: "button", className: "ui-app__search", "aria-haspopup": "dialog", onClick: () => setSearch(true), children: [
+          /* @__PURE__ */ jsx25("span", { className: "ui-app__search-ic", children: /* @__PURE__ */ jsx25(Icon, { name: "search" }) }),
+          /* @__PURE__ */ jsx25("span", { className: "ui-app__search-txt", children: "Search or run a command\u2026" }),
+          /* @__PURE__ */ jsx25("kbd", { className: "ui-cmdk__key", children: paletteHotkey() })
+        ] }),
+        /* @__PURE__ */ jsx25("span", { className: "ui-app__bar-gap" }),
+        bandControl,
+        /* @__PURE__ */ jsx25("button", { type: "button", className: "toggle", "aria-label": themeName(theme), title: themeName(theme), onClick: () => applyTheme(theme === "light" ? "dark" : "light"), children: /* @__PURE__ */ jsx25("span", { className: "ic", "aria-hidden": "true", dangerouslySetInnerHTML: { __html: themeIcon(theme) } }) }),
+        /* @__PURE__ */ jsx25("div", { className: "ui-app__user ui-app__user--bar", children: /* @__PURE__ */ jsx25(
+          Dropdown,
+          {
+            variant: "menu",
+            align: "end",
+            chevron: false,
+            ariaLabel: `Signed in as ${account.name}, ${account.email}`,
+            triggerClass: "ui-app__user-trigger",
+            panelClass: "ui-app__user-panel",
+            triggerContent: /* @__PURE__ */ jsx25("span", { className: "ui-app__av", "aria-hidden": "true", children: initials }),
+            header: /* @__PURE__ */ jsxs21("div", { className: "ui-dropdown__head", children: [
+              /* @__PURE__ */ jsx25("b", { children: account.name }),
+              /* @__PURE__ */ jsx25("span", { children: account.email })
+            ] }),
+            items: [{ label: "Sign out", icon: "logout", danger: true }],
+            onSelect: onSignOut
+          }
+        ) })
+      ] }),
+      /* @__PURE__ */ jsxs21("main", { className: `ui-app__main${width === "wide" ? " ui-app__main--wide" : ""}`, children: [
+        back && /* @__PURE__ */ jsx25(BackLink, { ...back }),
+        /* @__PURE__ */ jsx25("h1", { children: title }),
+        lede && /* @__PURE__ */ jsx25("p", { className: "ui-app__sub", children: lede }),
+        actions && /* @__PURE__ */ jsx25("div", { className: "ui-react-app__actions", children: actions }),
+        /* @__PURE__ */ jsx25("div", { className: "ui-app__body", children })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx25("nav", { className: "ui-nav ui-react-app__bottom", "aria-label": "Sections on mobile", children: /* @__PURE__ */ jsxs21("ul", { className: "ui-nav__list", children: [
+      links(visible),
+      remaining.length > 0 && /* @__PURE__ */ jsx25("li", { children: /* @__PURE__ */ jsxs21(
+        "button",
+        {
+          type: "button",
+          className: `ui-nav__item${active && remaining.includes(active) ? " is-active" : ""}`,
+          "aria-haspopup": "dialog",
+          "aria-expanded": more,
+          onClick: () => setMore(true),
+          children: [
+            /* @__PURE__ */ jsx25("span", { className: "ui-nav__ic", children: /* @__PURE__ */ jsx25(Icon, { name: "moreHorizontal" }) }),
+            /* @__PURE__ */ jsx25("span", { className: "ui-nav__label", children: "More" })
+          ]
+        }
+      ) })
+    ] }) }),
+    /* @__PURE__ */ jsx25(Drawer, { open: more, onClose: () => setMore(false), title: "More sections", side: "bottom", children: /* @__PURE__ */ jsx25("nav", { className: "ui-nav ui-nav--side", "aria-label": "More sections", children: /* @__PURE__ */ jsx25("ul", { className: "ui-nav__list", children: links(remaining) }) }) }),
+    /* @__PURE__ */ jsx25(CommandPalette, { ...palette ?? { groups: [{ items: sections.map((section) => ({ id: section.href, ...section })) }] }, open: search, onClose: () => setSearch(false) })
+  ] });
+}
+
 // src/index.ts
 var PAGE_SIZES = KIT_PAGE_SIZES;
 var DEFAULT_PAGE_SIZE3 = KIT_DEFAULT_PAGE_SIZE;
 export {
+  AppShell,
   BackLink,
   Badge,
   BusyRegion,