@tempoxyz/ds 0.3.0 → 0.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tempoxyz/ds",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "files": [
     "DESIGN.md",

package/src/web/components/Alert.tsx

@@ -48,7 +48,8 @@ export namespace Alert {
 
   /**
    * A text `<button>` with a 44px tall target, in the alert's strong type. Place it inside
-   * `Alert.Content`, after the message. Name the action it performs, such as Review fees.
+   * `Alert.Content`, after the message, or at the end of the row, where its label sits in line
+   * with the first line. Name the action it performs, such as Review fees.
    */
   export function Action(props: Action.Props) {
     const { className, vars, ...attributes } = props
@@ -70,7 +71,8 @@ export namespace Alert {
 
   /**
    * Stacks the title, message, and action in a `<div>` that fills the row and can shrink, so long
-   * text wraps beside the indicator.
+   * text wraps beside the indicator. The message flows as text. When it sits beside a paragraph or
+   * a list, wrap it in a `p`, so the blocks keep their 4px gap.
    */
   export function Content(props: Content.Props) {
     const { className, vars, ...attributes } = props
@@ -176,13 +178,28 @@ namespace styles {
     { id: 'tds/web/alert/action' },
   )
 
+  // The message flows as text, so inline elements such as `strong` stay on its lines. The title,
+  // the action and block children each take a line of their own, 4px from the content beside
+  // them.
   export const content = style(
     {
-      display: 'flex',
+      display: 'block',
       flex: '1 !custom',
-      flexDirection: 'column',
       minWidth: '0',
-      rowGap: '4',
+      selectors: {
+        '& > [data-alert-action]': {
+          display: 'flex',
+          marginBlockStart: '4',
+          width: 'fit-content !custom',
+        },
+        '& > [data-alert-title]': { marginBlockEnd: '4' },
+        // The browser's block margins of paragraphs and lists give way to the 4px gap. `:where`
+        // keeps the reset below any class that sets a margin of its own.
+        '& > :where(p, ul, ol)': { marginBlock: '0' },
+        // A list sits 4px below the message, and a paragraph 4px below the element before it. A
+        // list follows text in practice, which CSS cannot select, so it always takes the gap.
+        '& > :is(ul, ol), & > * + :is(p, div)': { marginBlockStart: '4' },
+      },
     },
     { id: 'tds/web/alert/content' },
   )
@@ -260,6 +277,9 @@ namespace styles {
         padding: '16',
         typography: 'body.b3',
         selectors: {
+          // An action at the end of the row centers its 44px target on the 16px first line, so its
+          // label stays in line with the message.
+          '& > [data-alert-action]': { marginBlock: 'calc((1rem - 2.75rem) / 2) !custom' },
           '& [data-alert-action], & [data-alert-title]': { typography: 'body.b3Strong' },
           '& [data-alert-icon]': { height: '16', width: '16' },
         },

package/src/web/components/AppShell.tsx

@@ -1,4 +1,5 @@
 import * as BaseUi from '@base-ui/react/drawer'
+import { useRender } from '@base-ui/react/use-render'
 import {
   type ComponentPropsWithRef,
   createContext,
@@ -9,8 +10,11 @@ import {
 import type * as zyzz from 'zyzz'
 import { keyframes } from 'zyzz/web'
 import { style, variants, vars } from '../zyzz.config.js'
+import * as TabBar from './internal/TabBar.js'
+import * as Text from './internal/Text.js'
 
 type Context = {
+  collapse: boolean
   container: HTMLDivElement | null
   handle: BaseUi.Drawer.Handle<unknown>
   open: boolean
@@ -19,10 +23,11 @@ type Context = {
 
 const context = createContext<Context | undefined>(undefined)
 
-const compactQuery = '(max-width: 1023px)'
+// The sidebar opens as a drawer below 1024px, or below 768px when it collapses to its icons from
+// 768px to 1023px. The breakpoints are literals because media queries cannot read CSS variables.
+function useCompact(collapse: boolean) {
+  const compactQuery = collapse ? '(max-width: 767px)' : '(max-width: 1023px)'
 
-// The viewport breakpoint is a literal because media queries cannot read CSS variables.
-function useCompact() {
   return useSyncExternalStore(
     (notify) => {
       const query = window.matchMedia(compactQuery)
@@ -112,7 +117,9 @@ export namespace AppShell {
   export function Root(props: Root.Props) {
     const {
       align,
+      children,
       className,
+      collapse = false,
       defaultOpen = false,
       onOpenChange,
       open,
@@ -121,6 +128,7 @@ export namespace AppShell {
       ...attributes
     } = props
     const [handle] = useState(() => BaseUi.Drawer.createHandle<unknown>())
+    const [tabBar] = useState(TabBar.create)
     const [uncontrolled, setUncontrolled] = useState(defaultOpen)
     const [container, setContainer] = useState<HTMLDivElement | null>(null)
     const current = open ?? uncontrolled
@@ -128,6 +136,7 @@ export namespace AppShell {
     return (
       <context.Provider
         value={{
+          collapse,
           container,
           handle,
           open: current,
@@ -140,13 +149,19 @@ export namespace AppShell {
         <div
           {...attributes}
           {...styles.root({ align, className, style: props.style, vars })}
+          data-app-shell-collapse={collapse ? '' : undefined}
           data-state={current ? 'open' : 'closed'}
           ref={(node) => {
             setContainer(node)
             if (typeof ref === 'function') ref(node)
             else if (ref) ref.current = node
           }}
-        />
+        >
+          <TabBar.Context.Provider value={tabBar}>
+            {children}
+            <BottomBar />
+          </TabBar.Context.Provider>
+        </div>
       </context.Provider>
     )
   }
@@ -154,6 +169,14 @@ export namespace AppShell {
   export namespace Root {
     export type Props = ComponentPropsWithRef<'div'> &
       zyzz.Props.Variants<typeof styles.root> & {
+        /**
+         * Collapses the inline sidebar to a 64px column of icons from 768px to 1023px, and opens
+         * the drawer only below 768px. Give every `SidebarMenu.Item` an icon as its first child.
+         * Absent, the sidebar opens as a drawer below 1024px.
+         * @default false
+         */
+        collapse?: boolean | undefined
+
         /**
          * Initial drawer state when `open` is uncontrolled.
          * @default false
@@ -177,10 +200,18 @@ export namespace AppShell {
   export function Sidebar(props: Sidebar.Props) {
     const { className, vars, ...attributes } = props
     const shell = useShell()
-    const compact = useCompact()
+    const compact = useCompact(shell.collapse)
     const sidebar = styles.sidebar({ className, style: props.style, vars })
 
-    if (!compact) return <aside {...attributes} {...styles.inline(sidebar)} />
+    if (!compact)
+      return (
+        <aside
+          {...attributes}
+          {...styles.inline(sidebar)}
+          data-app-shell-rail={shell.collapse ? '' : undefined}
+          data-app-shell-sidebar="inline"
+        />
+      )
 
     return (
       <BaseUi.Drawer.Root
@@ -189,7 +220,8 @@ export namespace AppShell {
         open={shell.open}
         swipeDirection="right"
       >
-        <BaseUi.Drawer.Portal container={shell.container}>
+        {/* The closed drawer stays mounted, so its items register in the bottom bar. */}
+        <BaseUi.Drawer.Portal container={shell.container} keepMounted>
           <BaseUi.Drawer.Backdrop {...styles.backdrop()} />
           <BaseUi.Drawer.Viewport {...styles.viewport()}>
             <BaseUi.Drawer.Popup
@@ -292,6 +324,54 @@ export namespace AppShell {
   }
 }
 
+/**
+ * Repeats the `SidebarMenu.Item`s that set `tabBar` in a bar fixed to the bottom edge below 768px:
+ * `tab` items as icons in a pill `<nav>`, then each `action` item as a floating action button.
+ * Renders nothing while no item sets `tabBar`.
+ */
+function BottomBar() {
+  const store = use(TabBar.Context)!
+  const entries = useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot)
+  const tabs = entries.filter(([, entry]) => entry.variant === 'tab')
+  const actions = entries.filter(([, entry]) => entry.variant === 'action')
+
+  if (entries.length === 0) return null
+
+  return (
+    <div {...styles.bottomBar()} data-app-shell-bottom-bar="">
+      {tabs.length > 0 && (
+        <nav aria-label="Main" {...styles.tabBar()}>
+          {tabs.map(([id, entry]) => (
+            <BottomBarItem entry={entry} key={id} />
+          ))}
+        </nav>
+      )}
+      {actions.map(([id, entry]) => (
+        <BottomBarItem entry={entry} key={id} />
+      ))}
+    </div>
+  )
+}
+
+/**
+ * Renders the element of a `SidebarMenu.Item` with the attributes and `render` of the item, and
+ * shows only its first element, such as its icon. Its text stays in the accessible name.
+ */
+function BottomBarItem(props: { entry: TabBar.Entry }) {
+  const { entry } = props
+
+  return useRender({
+    defaultTagName: 'a',
+    props: {
+      ...entry.attributes,
+      'aria-current': entry.active ? 'page' : undefined,
+      ...(entry.variant === 'tab' ? styles.tab({ active: entry.active }) : styles.action()),
+      children: Text.wrap(entry.children, styles.label()),
+    },
+    render: entry.render,
+  })
+}
+
 const fadeIn = keyframes(
   { from: { opacity: 0 }, to: { opacity: 1 } },
   { id: 'tds/web/app-shell/fade-in' },
@@ -303,6 +383,53 @@ const fadeOut = keyframes(
 )
 
 namespace styles {
+  // The 56px circle of the Platform Floating Action Button, filled like the primary button.
+  export const action = style(
+    {
+      alignItems: 'center',
+      backgroundColor: 'inverse.background.primary',
+      borderRadius: 'full',
+      boxShadow: 'large',
+      boxSizing: 'border-box',
+      color: 'inverse.content.primary',
+      cornerShape: 'round',
+      cursor: 'pointer',
+      display: 'flex',
+      flexShrink: '0 !custom',
+      height: '56',
+      justifyContent: 'center',
+      outlineColor: 'transparent !custom',
+      outlineOffset: '2',
+      outlineStyle: 'solid !custom',
+      outlineWidth: '2',
+      position: 'relative',
+      textDecoration: 'none !custom',
+      transitionDuration: '160',
+      transitionProperty: 'background-color, outline-color, scale !custom',
+      transitionTimingFunction: 'snappy',
+      width: '56',
+      selectors: {
+        '& > :first-child': { flexShrink: '0 !custom', fontSize: '24' },
+        '& > :not(:first-child)': {
+          clipPath: 'inset(50%) !custom',
+          height: '1px !custom',
+          overflow: 'hidden',
+          position: 'absolute',
+          whiteSpace: 'nowrap',
+          width: '1px !custom',
+        },
+        '&:active': { scale: 'press', transitionDuration: '100' },
+        '&:focus-visible': { outlineColor: 'border.focus' },
+        '&:hover': { backgroundColor: 'action.primary.fill.hover' },
+      },
+      '@media (prefers-reduced-motion: reduce)': {
+        transitionProperty: 'background-color, outline-color !custom',
+        selectors: { '&:active': { scale: 'none !custom' } },
+      },
+    },
+    { id: 'tds/web/app-shell/action' },
+  )
+
   export const backdrop = style(
     {
       backgroundColor: 'neutral.100',
@@ -350,6 +477,22 @@ namespace styles {
     { id: 'tds/web/app-shell/bar' },
   )
 
+  // Floats over the content, inset by the 24px page margin of the Mobile layout and 16px from the
+  // bottom edge. It sits below the drawer and its backdrop.
+  export const bottomBar = style(
+    {
+      alignItems: 'center',
+      bottom: 'calc(1rem + env(safe-area-inset-bottom)) !custom',
+      columnGap: '12',
+      display: 'none',
+      insetInline: '24',
+      position: 'fixed',
+      zIndex: '39 !custom',
+      '@media (max-width: 767px)': { display: 'flex' },
+    },
+    { id: 'tds/web/app-shell/bottom-bar' },
+  )
+
   export const bars = style(
     { display: 'block', height: '16', position: 'relative', width: '16' },
     { id: 'tds/web/app-shell/bars' },
@@ -375,6 +518,9 @@ namespace styles {
         },
         '&[data-starting-style]': { transform: 'translateX(100%) !custom' },
         '&[data-swiping]': { transitionDuration: '0', userSelect: 'none' },
+        // The closed drawer stays mounted with the `hidden` attribute, which the flex layout of
+        // the sidebar would override.
+        '&[hidden]': { display: 'none !custom' },
       },
       '@media (prefers-reduced-motion: reduce)': {
         transitionProperty: 'opacity !custom',
@@ -411,8 +557,11 @@ namespace styles {
         paddingInline: '16',
         '@media (min-width: 640px)': { marginInline: '-2rem !custom', paddingInline: '24' },
         // Below 1024px the fixed trigger covers the end of the bar, so header actions end 8px
-        // before it: its 40px plus its 16px inset.
+        // before it: its 40px plus its 16px inset. A collapsed sidebar hides it from 768px.
         '@media (max-width: 1023px)': { paddingInlineEnd: '64' },
+        '@media (min-width: 768px) and (max-width: 1023px)': {
+          selectors: { '[data-app-shell-collapse] > main > &': { paddingInlineEnd: '24' } },
+        },
       },
     },
     { id: 'tds/web/app-shell/header' },
@@ -454,6 +603,15 @@ namespace styles {
         '@media (max-width: 1023px)': {
           selectors: { '&::after, &::before': { display: 'none !custom' } },
         },
+        // The bottom bar covers the end of the page, so content can scroll clear of it: 16px
+        // below the bar, its 56px, and 16px above it.
+        '@media (max-width: 767px)': {
+          selectors: {
+            '&:has(> [data-app-shell-bottom-bar]) > main': {
+              paddingBottom: 'calc(5.5rem + env(safe-area-inset-bottom)) !custom',
+            },
+          },
+        },
       },
       defaultVariants: { align: 'center' },
       variants: {
@@ -504,6 +662,19 @@ namespace styles {
     { id: 'tds/web/app-shell/sidebar' },
   )
 
+  // Keeps the label of a bottom bar item in its accessible name without painting it.
+  export const label = style(
+    {
+      clipPath: 'inset(50%) !custom',
+      height: '1px !custom',
+      overflow: 'hidden',
+      position: 'absolute',
+      whiteSpace: 'nowrap',
+      width: '1px !custom',
+    },
+    { id: 'tds/web/app-shell/label' },
+  )
+
   // Follows `sidebar`, so its compact `display: none` overrides the sidebar's `display: flex` in
   // server-rendered markup, which always emits the wide layout.
   export const inline = style(
@@ -517,6 +688,12 @@ namespace styles {
       position: 'sticky',
       width: 'var(--sidebar-width, 16rem) !custom',
       '@media (max-width: 1023px)': { display: 'none !custom' },
+      // A collapsed sidebar stays inline as a column of icons, which `SidebarMenu` centers.
+      '@media (min-width: 768px) and (max-width: 1023px)': {
+        selectors: {
+          '&[data-app-shell-rail]': { display: 'flex !custom', width: '4rem !custom' },
+        },
+      },
     },
     { id: 'tds/web/app-shell/inline' },
   )
@@ -538,6 +715,15 @@ namespace styles {
         // Classic scrollbars keep their own lane instead of covering content at the edge.
         scrollbarGutter: 'stable',
         scrollbarWidth: 'thin',
+        // The collapsed sidebar has no room for a scrollbar lane beside its 40px icons.
+        '@media (min-width: 768px) and (max-width: 1023px)': {
+          selectors: {
+            '[data-app-shell-rail] &': {
+              scrollbarGutter: 'auto !custom',
+              scrollbarWidth: 'none !custom',
+            },
+          },
+        },
         selectors: {
           // Curtains fade content into the sidebar at whichever end has more to scroll.
           '&::after, &::before': {
@@ -598,6 +784,81 @@ namespace styles {
     { id: 'tds/web/app-shell/sidebar-header' },
   )
 
+  // An icon-only item of the Platform Tab Bar, which fills its share of the pill.
+  export const tab = variants(
+    {
+      base: {
+        alignItems: 'center',
+        borderRadius: 'full',
+        boxSizing: 'border-box',
+        color: 'content.secondary',
+        cornerShape: 'round',
+        cursor: 'pointer',
+        display: 'flex',
+        flex: '1 !custom',
+        height: '100% !custom',
+        justifyContent: 'center',
+        minWidth: '0',
+        outlineColor: 'transparent !custom',
+        outlineOffset: '-2',
+        outlineStyle: 'solid !custom',
+        outlineWidth: '2',
+        position: 'relative',
+        textDecoration: 'none !custom',
+        transitionDuration: '160',
+        transitionProperty: 'background-color, color, outline-color, scale !custom',
+        transitionTimingFunction: 'snappy',
+        selectors: {
+          '& > :first-child': { flexShrink: '0 !custom', fontSize: '24' },
+          '& > :not(:first-child)': {
+            clipPath: 'inset(50%) !custom',
+            height: '1px !custom',
+            overflow: 'hidden',
+            position: 'absolute',
+            whiteSpace: 'nowrap',
+            width: '1px !custom',
+          },
+          '&:active': { scale: 'press', transitionDuration: '100' },
+          '&:focus-visible': { outlineColor: 'border.focus' },
+          '&:hover': { color: 'content.primary' },
+        },
+        '@media (prefers-reduced-motion: reduce)': {
+          transitionProperty: 'background-color, color, outline-color !custom',
+          selectors: { '&:active': { scale: 'none !custom' } },
+        },
+      },
+      defaultVariants: { active: false },
+      variants: {
+        active: {
+          false: {},
+          true: { backgroundColor: 'container.regular', color: 'content.primary' },
+        },
+      },
+    },
+    { id: 'tds/web/app-shell/tab' },
+  )
+
+  // The 56px pill of the Platform Tab Bar, which takes the width beside the action button.
+  export const tabBar = style(
+    {
+      alignItems: 'center',
+      backgroundColor: 'background.secondary',
+      borderColor: 'line.secondary',
+      borderRadius: 'full',
+      borderStyle: 'solid',
+      borderWidth: 'regular',
+      boxShadow: 'regular',
+      boxSizing: 'border-box',
+      cornerShape: 'round',
+      display: 'flex',
+      flex: '1 !custom',
+      height: '56',
+      minWidth: '0',
+      padding: '4',
+    },
+    { id: 'tds/web/app-shell/tab-bar' },
+  )
+
   export const title = variants(
     {
       base: {
@@ -654,6 +915,9 @@ namespace styles {
           },
         },
         '@media (min-width: 1024px)': { display: 'none !custom' },
+        '@media (min-width: 768px) and (max-width: 1023px)': {
+          selectors: { '[data-app-shell-collapse] &': { display: 'none !custom' } },
+        },
         '@media (prefers-reduced-motion: reduce)': {
           transitionProperty: 'background-color, outline-color, outline-offset !custom',
           selectors: { '&:active': { transform: 'none !custom' } },
@@ -670,6 +934,7 @@ namespace styles {
       justifyContent: 'flex-end',
       position: 'fixed',
       zIndex: 'popover',
+      selectors: { '&[hidden]': { display: 'none !custom' } },
     },
     { id: 'tds/web/app-shell/viewport' },
   )

package/src/web/components/Badge.tsx

@@ -104,8 +104,10 @@ namespace styles {
           // The accent text follows the inverse content color, which turns black in dark mode.
           accent: { backgroundColor: 'accent.blue.background', color: 'inverse.content.primary' },
           elevated: { backgroundColor: 'background.elevated', color: 'content.primary' },
-          // The inverse fill stays dark in both schemes, so its text stays white.
-          inverse: { backgroundColor: 'inverse.background.secondary', color: 'neutral.000' },
+          inverse: {
+            backgroundColor: 'inverse.background.secondary',
+            color: 'inverse.content.primary',
+          },
           outlined: {
             backgroundColor: 'transparent !custom',
             borderColor: 'line.secondary',

package/src/web/components/Button.tsx

@@ -12,6 +12,7 @@ import { Spinner } from './Spinner.js'
  * - Use `Button` for actions and `Button.Link` for navigation.
  * - Label with a specific verb, such as Send payment. Give `shape="icon"` buttons, which render as circles, an `aria-label`.
  * - Keep one `primary` button per view or section, and give the others `secondary` or `tertiary`.
+ * - Use `danger` for the action that confirms a destructive outcome, such as Revoke key.
  * - Set `appearance="inverse"` on an inverse surface, such as a dark banner on a light page, and
  *   `appearance="overlay"` over an image or video.
  * - Use `large` for the actions in a dialog footer. Keep `xsmall` pills for actions inside a row
@@ -162,18 +163,11 @@ namespace styles {
             selectors: { '& > span:first-child': { minWidth: '0 !custom' } },
           },
         },
-        // The Platform Icon Button keeps its primary fill dark in both schemes, so its icon stays
-        // white. Hover and press take the primary action fills, which turn light in dark mode, so
-        // the icon takes the inverse content color over them.
+        // The Platform Icon Button fills its primary circle a step lighter than the primary
+        // Button in light mode.
         {
           when: { appearance: 'base', shape: 'icon', variant: 'primary' },
-          style: {
-            backgroundColor: 'inverse.background.secondary',
-            color: 'neutral.000',
-            selectors: {
-              '&:is(:hover, :active):not(:disabled)': { color: 'inverse.content.primary' },
-            },
-          },
+          style: { backgroundColor: 'inverse.background.secondary' },
         },
         // The focus ring of the page blends into an inverse surface, so an inverse button draws
         // its ring in the inverse text color, 2px out, where the surface separates it from a fill
@@ -278,6 +272,16 @@ namespace styles {
         // Each pressed fill follows its hover fill, so it wins while the pointer stays over the
         // button.
         variant: {
+          // The Platform Button has no pressed design for `danger`, so a press keeps the hover fill.
+          danger: {
+            backgroundColor: 'action.danger.fill.rest',
+            color: 'action.danger.label.rest',
+            selectors: {
+              '&:is(:hover, :active):not(:disabled)': {
+                backgroundColor: 'action.danger.fill.hover',
+              },
+            },
+          },
           // The Platform Button paints its primary fill and label with the inverse colors.
           primary: {
             backgroundColor: 'inverse.background.primary',

package/src/web/components/Dialog.tsx

@@ -75,7 +75,13 @@ export namespace Dialog {
   export function Body(props: Body.Props) {
     const { className, vars, ...attributes } = props
 
-    return <div {...attributes} {...styles.body({ className, style: props.style, vars })} />
+    return (
+      <div
+        {...attributes}
+        data-dialog-body=""
+        {...styles.body({ className, style: props.style, vars })}
+      />
+    )
   }
 
   export namespace Body {