@tempoxyz/ds 0.2.0 → 0.2.2

package/src/oxlint/rules/RequireAccessibleName.ts

@@ -0,0 +1,132 @@
+/** Requires a name on `@tempoxyz/ds` components that render no text of their own. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Imports from '../internal/Imports.ts'
+
+type Target = {
+  /** Attributes that name the element. */
+  readonly names: readonly string[]
+  /** An attribute and value that make the component icon-only. When absent, every use needs a name. */
+  readonly when?: { readonly attribute: string; readonly value: string } | undefined
+}
+
+const list = new Intl.ListFormat('en', { type: 'disjunction' })
+const web = ['aria-label', 'aria-labelledby']
+const mobile = ['accessibilityLabel', 'accessibilityLabelledBy', 'aria-label', 'aria-labelledby']
+
+// Components from each surface whose rendered output has no text to name it.
+const targets: Record<Imports.Surface, Record<string, Target>> = {
+  mobile: { IconButton: { names: mobile } },
+  web: {
+    Button: { names: web, when: { attribute: 'shape', value: 'icon' } },
+    'Button.Link': { names: web, when: { attribute: 'shape', value: 'icon' } },
+    Gauge: { names: web },
+  },
+}
+
+/**
+ * Reports an icon-only `Button` or `Button.Link`, a `Gauge`, or a Mobile `IconButton` without an
+ * accessible name. An element passed to a `render` prop can take its name from the element that
+ * owns the prop. Elements with a spread attribute are skipped, since the spread can supply the name.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Name `@tempoxyz/ds` components that render no text.' },
+    messages: {
+      missing: "'{{component}}' renders no text. Name it with {{names}}.",
+    },
+    schema: [],
+    type: 'problem',
+  },
+  create(context) {
+    type Binding = { imported: string | undefined; surface: Imports.Surface }
+
+    const bindings = new Map<string, Binding>()
+
+    function attribute(node: ESTree.JSXOpeningElement, name: string) {
+      return node.attributes.find(
+        (attribute): attribute is ESTree.JSXAttribute =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name.type === 'JSXIdentifier' &&
+          attribute.name.name === name,
+      )
+    }
+
+    function literal(node: ESTree.JSXAttribute) {
+      const value =
+        node.value?.type === 'JSXExpressionContainer' ? node.value.expression : node.value
+
+      return value?.type === 'Literal' ? value.value : undefined
+    }
+
+    function named(target: Target, node: ESTree.JSXOpeningElement) {
+      if (node.attributes.some((attribute) => attribute.type === 'JSXSpreadAttribute')) return true
+
+      return target.names.some((name) => {
+        const found = attribute(node, name)
+
+        return found !== undefined && literal(found) !== ''
+      })
+    }
+
+    function path(node: ESTree.JSXElementName | ESTree.JSXMemberExpressionObject): string[] {
+      if (node.type === 'JSXIdentifier') return [node.name]
+      if (node.type === 'JSXMemberExpression') return [...path(node.object), node.property.name]
+      return []
+    }
+
+    return {
+      ImportDeclaration(node) {
+        const surface = Imports.surface(node.source.value)
+
+        if (!surface || node.importKind === 'type') return
+        for (const specifier of node.specifiers) {
+          if (specifier.type === 'ImportNamespaceSpecifier')
+            bindings.set(specifier.local.name, { imported: undefined, surface })
+          if (specifier.type === 'ImportSpecifier' && specifier.importKind !== 'type')
+            bindings.set(specifier.local.name, {
+              imported:
+                specifier.imported.type === 'Identifier'
+                  ? specifier.imported.name
+                  : String(specifier.imported.value),
+              surface,
+            })
+        }
+      },
+      JSXOpeningElement(node) {
+        const [head, ...rest] = path(node.name)
+        const binding = head === undefined ? undefined : bindings.get(head)
+
+        if (!binding) return
+
+        const component = (binding.imported ? [binding.imported, ...rest] : rest).join('.')
+        const target = targets[binding.surface][component]
+
+        if (!target) return
+        if (target.when) {
+          const condition = attribute(node, target.when.attribute)
+
+          if (!condition || literal(condition) !== target.when.value) return
+        }
+
+        // An element passed to `render` takes its attributes from the element that owns the prop.
+        const owner = (() => {
+          for (let parent: ESTree.Node | null = node.parent; parent; parent = parent.parent)
+            if (
+              parent.type === 'JSXAttribute' &&
+              parent.name.type === 'JSXIdentifier' &&
+              parent.name.name === 'render'
+            )
+              return parent.parent.type === 'JSXOpeningElement' ? parent.parent : undefined
+          return undefined
+        })()
+
+        if (!named(target, node) && (!owner || !named(target, owner)))
+          context.report({
+            data: { component, names: list.format(target.names.map((name) => `\`${name}\``)) },
+            messageId: 'missing',
+            node,
+          })
+      },
+    }
+  },
+}

package/src/web/components/Amount.tsx

@@ -3,9 +3,9 @@ import type * as zyzz from 'zyzz'
 import { style, variants } from '../zyzz.config.js'
 
 /**
- * Formats a number in the user's locale inside a `span` with tabular figures. `currency` formats
- * an ISO 4217 code as money, and `symbol` follows the number with a token symbol. The two are
- * mutually exclusive.
+ * Formats a number in `en-US`, or in `locale` when set, inside a `span` with tabular figures.
+ * `currency` formats an ISO 4217 code as money, and `symbol` follows the number with a token
+ * symbol. The two are mutually exclusive.
  *
  * - Pass amounts as decimal strings to avoid floating-point rounding.
  * - Always pass `currency` or `symbol` so the unit does not depend on surrounding context.
@@ -24,6 +24,7 @@ export function Amount(props: Amount.Props) {
   const {
     className,
     currency,
+    locale,
     maxDecimals,
     precise,
     sign,
@@ -48,7 +49,7 @@ export function Amount(props: Amount.Props) {
       })}
     >
       {sign}
-      {format({ currency, maxDecimals, precise, value })}
+      {format({ currency, locale, maxDecimals, precise, value })}
       {symbol && <span {...styles.symbol()}> {symbol}</span>}
     </span>
   )
@@ -57,6 +58,13 @@ export function Amount(props: Amount.Props) {
 export namespace Amount {
   export type Props = Omit<ComponentPropsWithRef<'span'>, 'children'> &
     zyzz.Props.Variants<typeof styles.amount> & {
+      /**
+       * BCP 47 tag, such as `de-DE`, for grouping, decimal marks, and currency symbols. The default
+       * does not depend on the runtime locale, so server and browser render the same text. A tag
+       * that `Intl` rejects, such as `""` or `"en_US"`, falls back to `en-US` instead of throwing.
+       * @default 'en-US'
+       */
+      locale?: string | undefined
       /**
        * Caps the fraction digits shown. With `currency`, it never exceeds the currency's own digits
        * and sets the exact count, so `0` renders `$5`.
@@ -88,29 +96,41 @@ export namespace Amount {
     )
 }
 
-function format(options: Pick<Amount.Props, 'currency' | 'maxDecimals' | 'precise' | 'value'>) {
+function format(
+  options: Pick<Amount.Props, 'currency' | 'locale' | 'maxDecimals' | 'precise' | 'value'>,
+) {
   const { currency, maxDecimals, precise, value } = options
   // ES2023 formats decimal strings exactly. The signature keeps ES2022 libs compiling.
   const exact = (formatter: Intl.NumberFormat) =>
     (formatter.format as (value: number | string) => string)(value)
 
+  // `Intl.NumberFormat` throws for a malformed tag and replaces an unsupported one with the
+  // runtime locale, so both resolve to `en-US` here.
+  const locale = (() => {
+    try {
+      return Intl.NumberFormat.supportedLocalesOf(options.locale)[0] ?? 'en-US'
+    } catch {
+      return 'en-US'
+    }
+  })()
+
   if (currency) {
     const money = { currency, style: 'currency' } as const
-    const max = new Intl.NumberFormat(undefined, money).resolvedOptions().maximumFractionDigits!
+    const max = new Intl.NumberFormat(locale, money).resolvedOptions().maximumFractionDigits!
     const digits = Math.min(maxDecimals ?? max, max)
     const number = Number(value)
     const sub = number !== 0 && Math.abs(number) < 10 ** -digits
 
     if (sub && precise)
       return exact(
-        new Intl.NumberFormat(undefined, {
+        new Intl.NumberFormat(locale, {
           ...money,
           maximumFractionDigits: 20,
           maximumSignificantDigits: 2,
         }),
       )
 
-    const formatter = new Intl.NumberFormat(undefined, {
+    const formatter = new Intl.NumberFormat(locale, {
       ...money,
       maximumFractionDigits: digits,
       minimumFractionDigits: digits,
@@ -124,7 +144,7 @@ function format(options: Pick<Amount.Props, 'currency' | 'maxDecimals' | 'precis
   const digits = Math.min(maxDecimals ?? fraction, fraction)
 
   return exact(
-    new Intl.NumberFormat(undefined, {
+    new Intl.NumberFormat(locale, {
       maximumFractionDigits: digits,
       minimumFractionDigits: typeof value === 'string' ? digits : 0,
     }),

package/src/web/components/AmountInput.tsx

@@ -6,8 +6,21 @@ import { Input } from './Input.js'
 import * as AmountContext from './internal/AmountContext.js'
 
 /**
- * Decimal amount entry. The value is a raw string without grouping commas, and input that is
- * not a non-negative decimal is rejected.
+ * Decimal amount entry. The value is a raw string with a dot separator and no grouping
+ * separators, and input that is not a non-negative decimal is rejected.
+ *
+ * The text around a comma decides whether it groups thousands or separates decimals:
+ *
+ * - With both a dot and a comma, the last one separates decimals and the other groups thousands:
+ *   `1,250.50` and `1.250,50` are both `1250.50`.
+ * - Several commas group thousands: `1,250,000` is `1250000`.
+ * - A lone comma groups thousands after one to three digits that do not start with `0`, when
+ *   exactly three digits follow it: `1,250` is `1250`.
+ * - Any other lone comma separates decimals: `1,5` is `1.5`, `0,250` is `0.250`, `1234,567` is
+ *   `1234.567`, and `12,` is `12.`.
+ *
+ * The field shows a lone comma as typed until a dot or a second comma settles it, then shows the
+ * value.
  *
  * `Control` is a text input with `inputMode="decimal"`, so mobile keyboards show digits without
  * the scroll and spinner behavior of `type="number"`.
@@ -46,10 +59,8 @@ export namespace AmountInput {
         value={{
           value,
           setValue(next) {
-            const clean = next.replaceAll(',', '')
-            if (!/^\d*\.?\d*$/.test(clean)) return
-            setUncontrolled(clean)
-            onValueChange?.(clean)
+            setUncontrolled(next)
+            onValueChange?.(next)
           },
         }}
       >
@@ -70,9 +81,11 @@ export namespace AmountInput {
   /** Text field whose digits morph as the value changes. Motion stops under reduced motion. */
   export function Control(props: Control.Props) {
     const amount = AmountContext.use()
-    const [typed, setTyped] = useState<{ caret: number | null; value: string }>()
+    const [typed, setTyped] = useState<{ caret: number | null; text: string; value: string }>()
     // Typed edits morph at the caret. Other changes, such as Max, roll digits by place value.
-    const caret = typed?.value === amount.value ? (typed.caret ?? undefined) : undefined
+    const edit = typed?.value === amount.value ? typed : undefined
+    const caret = edit?.caret ?? undefined
+    const text = edit?.text ?? amount.value
 
     return (
       <span {...styles.control()}>
@@ -82,15 +95,20 @@ export namespace AmountInput {
           {...props}
           {...styles.input({ className: props.className, style: props.style })}
           onValueChange={(next, details) => {
+            const value = parse(next)
+            if (value === undefined) return
+
             const input = details.event.target as HTMLInputElement
-            setTyped({ caret: input.selectionStart, value: next.replaceAll(',', '') })
-            amount.setValue(next)
+            // The digits typed after a lone comma can still change its role, so it stays in place.
+            const lone = !next.includes('.') && next.split(',').length === 2
+            setTyped({ caret: input.selectionStart, text: lone ? next : value, value })
+            amount.setValue(value)
           }}
           type="text"
-          value={amount.value}
+          value={text}
         />
         <span aria-hidden="true" {...styles.morph()}>
-          <TextMorph {...(caret !== undefined && { cursorIndex: caret })}>{amount.value}</TextMorph>
+          <TextMorph {...(caret !== undefined && { cursorIndex: caret })}>{text}</TextMorph>
         </span>
       </span>
     )
@@ -133,6 +151,24 @@ export namespace AmountInput {
   export const Suffix = Input.Suffix
 }
 
+/** Returns the raw decimal for typed text, or `undefined` when it is not a non-negative decimal. */
+function parse(text: string) {
+  const value = (() => {
+    const dot = text.lastIndexOf('.')
+    if (dot !== -1 && text.lastIndexOf(',') > dot)
+      return text.replaceAll('.', '').replaceAll(',', '.')
+
+    // Grouping needs a first group of one to three digits without a leading zero, so `0,250` and
+    // `1234,567` are decimals.
+    if (/^[^,.]*,[^,.]*$/.test(text) && !/^[1-9]\d{0,2},\d{3}$/.test(text))
+      return text.replace(',', '.')
+
+    return text.replaceAll(',', '')
+  })()
+
+  return /^\d*\.?\d*$/.test(value) ? value : undefined
+}
+
 namespace styles {
   export const control = style(
     {

package/src/web/components/Banner.tsx

@@ -1,7 +1,7 @@
 import * as BaseUi from '@base-ui/react/button'
 import type { ComponentPropsWithRef } from 'react'
 import type * as zyzz from 'zyzz'
-import { Close } from '../icons/index.js'
+import { Close } from '../icons/Close.js'
 import { style, variants } from '../zyzz.config.js'
 
 /**

package/src/web/components/Calendar.tsx

@@ -165,12 +165,11 @@ export function Calendar(props: Calendar.Props) {
     if (!target) return
 
     event.preventDefault()
-    const clamped =
-      min !== undefined && key(target) < key(min)
-        ? min
-        : max !== undefined && key(target) > key(max)
-          ? max
-          : target
+    const clamped = (() => {
+      if (min !== undefined && key(target) < key(min)) return min
+      if (max !== undefined && key(target) > key(max)) return max
+      return target
+    })()
     pendingFocus.current = true
     setFocused(clamped)
     if (!sameMonth(clamped, month)) showMonth(clamped)

package/src/web/components/Callout.tsx

@@ -2,7 +2,10 @@ import * as BaseUi from '@base-ui/react/button'
 import { createContext, useContext } from 'react'
 import type { ComponentPropsWithRef } from 'react'
 import type * as zyzz from 'zyzz'
-import { AlertCircle, AlertTriangle, CheckCircle, InfoCircle } from '../icons/index.js'
+import { AlertCircle } from '../icons/AlertCircle.js'
+import { AlertTriangle } from '../icons/AlertTriangle.js'
+import { CheckCircle } from '../icons/CheckCircle.js'
+import { InfoCircle } from '../icons/InfoCircle.js'
 import { style, variants } from '../zyzz.config.js'
 
 type Intent = NonNullable<zyzz.Props.Variants<typeof styles.note>['intent']>

package/src/web/components/DatePicker.tsx

@@ -332,7 +332,7 @@ namespace styles {
           '&[aria-invalid="true"]::before': { borderColor: 'red.800' },
           '&[aria-invalid="true"]:focus-visible': { outlineColor: 'red.800' },
           '&:focus-visible::before': { borderColor: 'transparent !custom' },
-          '&[data-placeholder]': { color: 'gray.700' },
+          '&[data-placeholder]': { color: 'gray.900' },
         },
         '@media (forced-colors: active)': {
           outlineStyle: 'none !custom',

package/src/web/components/Dialog.tsx

@@ -1,7 +1,7 @@
 import * as BaseUi from '@base-ui/react/dialog'
 import type { ComponentPropsWithRef } from 'react'
 import type * as zyzz from 'zyzz'
-import * as Icons from '../icons/index.js'
+import { Close as CloseIcon } from '../icons/Close.js'
 import { style } from '../zyzz.config.js'
 import { Button } from './Button.js'
 
@@ -90,7 +90,7 @@ export namespace Dialog {
                   <Button shape="icon" size="medium" variant="secondary" {...styles.close()} />
                 }
               >
-                <Icons.Close />
+                <CloseIcon />
               </BaseUi.Dialog.Close>
             )}
           </BaseUi.Dialog.Popup>

package/src/web/components/Drawer.tsx

@@ -1,7 +1,7 @@
 import * as BaseUi from '@base-ui/react/drawer'
 import type { ComponentPropsWithRef } from 'react'
 import type * as zyzz from 'zyzz'
-import * as Icons from '../icons/index.js'
+import { Close as CloseIcon } from '../icons/Close.js'
 import { style } from '../zyzz.config.js'
 import { Button } from './Button.js'
 import { styles as dialog } from './Dialog.js'
@@ -107,7 +107,7 @@ export namespace Drawer {
                   <Button shape="icon" size="medium" variant="secondary" {...dialog.close()} />
                 }
               >
-                <Icons.Close />
+                <CloseIcon />
               </BaseUi.Drawer.Close>
             )}
           </BaseUi.Drawer.Popup>

package/src/web/components/Field.tsx

@@ -1,5 +1,5 @@
 import * as BaseUi from '@base-ui/react/field'
-import { type ComponentPropsWithRef, useContext } from 'react'
+import { type ComponentPropsWithRef, useContext, useRef, useState } from 'react'
 import type * as zyzz from 'zyzz'
 import { style } from '../zyzz.config.js'
 import * as FieldVariant from './internal/FieldVariant.js'
@@ -37,21 +37,56 @@ export namespace Field {
    * Owns validity, dirty, touched and filled state for one control and shares the variant with the
    * controls inside. Without `variant`, it inherits the variant of an enclosing `Fieldset` or
    * `Field`, falling back to `default`.
+   *
+   * When a native `form` submit finds the control invalid, such as an empty `required` input, the
+   * field validates and shows `Field.Error`. Outside `onBlur` mode, it then revalidates on each
+   * change, as inside Base UI's `Form`. The browser still moves focus to the first invalid control.
+   *
+   * `checkValidity()` and `reportValidity()` validate the field only after the user has interacted
+   * with the control, when the browser already matches it as `:user-invalid`.
    */
   export function Root(props: Root.Props) {
-    const { className, size, success = false, variant, vars, ...attributes } = props
+    const actions = useRef<BaseUi.Field.Root.Actions | null>(null)
+    const {
+      actionsRef = actions,
+      className,
+      onInvalidCapture,
+      size,
+      success = false,
+      validationMode,
+      variant,
+      vars,
+      ...attributes
+    } = props
     const inherited = useContext(FieldVariant.Context)
     const resolved = variant ?? inherited ?? 'default'
+    const [submitted, setSubmitted] = useState(false)
 
     return (
       <FieldVariant.Context.Provider value={resolved}>
         <BaseUi.Field.Root
           {...attributes}
           {...styles.root({ className, style: props.style, vars })}
+          actionsRef={actionsRef}
           data-field=""
           data-field-size={size}
           data-success={success || undefined}
           data-variant={resolved}
+          onInvalidCapture={(event) => {
+            onInvalidCapture?.(event)
+
+            // Base UI runs submit validation only inside its own Form. A native form fires `invalid`
+            // on each failing control instead, and the event does not bubble. `checkValidity()` and
+            // `reportValidity()` fire it too, but only a submit attempt marks the form's controls
+            // `:user-invalid` first. `invalid` targets only form controls.
+            if (!(event.target as Element).matches(':user-invalid')) return
+
+            actionsRef.current?.validate()
+            setSubmitted(true)
+          }}
+          // Base UI's Form counts submits to revalidate `onSubmit` fields on change. A native
+          // form has no count, so a failed submit switches the field to `onChange`.
+          validationMode={submitted && validationMode !== 'onBlur' ? 'onChange' : validationMode}
         />
       </FieldVariant.Context.Provider>
     )

package/src/web/components/Input.tsx

@@ -262,7 +262,7 @@ namespace styles {
       selectors: {
         '&::-webkit-search-cancel-button': { appearance: 'none !custom', display: 'none' },
         '&::placeholder': {
-          color: 'grayAlpha.700',
+          color: 'grayAlpha.900',
           transitionDuration: '160ms !custom',
           transitionProperty: 'opacity !custom',
           transitionTimingFunction: 'snappy',

package/src/web/components/Kbd.tsx

@@ -1,24 +1,60 @@
-import type { ComponentPropsWithRef } from 'react'
+import { type ComponentPropsWithRef, useSyncExternalStore } from 'react'
 import type * as zyzz from 'zyzz'
 import { style, variants } from '../zyzz.config.js'
 
-const modifiers = [
-  ['ctrl', '⌃', 'Control'],
-  ['alt', '⌥', 'Option'],
-  ['shift', '⇧', 'Shift'],
-  ['meta', '⌘', 'Command'],
-] as const
+// Each platform lists its modifiers in its own conventional order, as label and spoken name.
+const modifiers = {
+  apple: [
+    ['ctrl', '⌃', 'Control'],
+    ['alt', '⌥', 'Option'],
+    ['shift', '⇧', 'Shift'],
+    ['meta', '⌘', 'Command'],
+  ],
+  linux: [
+    ['meta', 'Super', 'Super'],
+    ['ctrl', 'Ctrl', 'Control'],
+    ['alt', 'Alt', 'Alt'],
+    ['shift', 'Shift', 'Shift'],
+  ],
+  windows: [
+    ['meta', 'Win', 'Windows'],
+    ['ctrl', 'Ctrl', 'Control'],
+    ['alt', 'Alt', 'Alt'],
+    ['shift', 'Shift', 'Shift'],
+  ],
+} as const
+
+// The server snapshot keeps server and hydration markup identical. React then re-renders with the
+// browser's platform.
+function usePlatform(): keyof typeof modifiers {
+  return useSyncExternalStore(
+    () => () => {},
+    () => {
+      if (/Macintosh|iPad|iPhone|iPod/.test(navigator.userAgent)) return 'apple'
+      return navigator.userAgent.includes('Windows') ? 'windows' : 'linux'
+    },
+    () => 'apple',
+  )
+}
 
 /**
- * Shows a key or shortcut in a native `kbd` element. Each modifier prop adds its glyph before the
- * children, always in the order Control, Option, Shift, Command. Glyphs are hidden from assistive
- * tech, which reads the visually hidden name instead, so `<Kbd meta>K</Kbd>` reads as `Command K`.
+ * Shows a key or shortcut in a native `kbd` element. Each modifier prop adds a label before the
+ * children in the platform's conventional order: glyphs ordered Control, Option, Shift, Command on
+ * Apple platforms, and names ordered Win (Super on Linux), Ctrl, Alt, Shift elsewhere. Labels are
+ * hidden from assistive tech, which reads the visually hidden name instead, so `<Kbd mod>K</Kbd>`
+ * reads as `Command K` on a Mac and `Control K` on Windows.
+ *
+ * Without `platform`, the server and hydration render Apple glyphs, then the client switches to the
+ * browser's platform. If the request identifies the platform, such as in the `Sec-CH-UA-Platform`
+ * header, map it to `apple`, `linux`, or `windows` and pass it as `platform`, so the markup never
+ * changes. Any other value falls back to the browser's platform.
  *
  * - Pass the main key as children and modifiers as props, rather than typing glyphs into children.
+ * - Use `mod` for shortcuts that take Command on Apple platforms and Ctrl elsewhere.
  * - Single-character shortcuts need a way to turn them off or remap them.
  *
  * @example
- * <Kbd meta shift>
+ * <Kbd mod shift>
  *   P
  * </Kbd>
  *
@@ -27,16 +63,27 @@ const modifiers = [
  * @see {@link https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html | WCAG 2.2 Info and Relationships}
  */
 export function Kbd(props: Kbd.Props) {
-  const { alt, children, className, ctrl, meta, shift, size, vars, ...attributes } = props
-  const active = { alt, ctrl, meta, shift }
+  const detected = usePlatform()
+  const { alt, children, className, ctrl, meta, mod, platform, shift, size, vars, ...attributes } =
+    props
+  // Untyped data, such as a raw `Sec-CH-UA-Platform` header, can hold any value, including inherited
+  // keys such as `toString`. Every value outside `modifiers` falls back to detection.
+  const resolved =
+    platform !== undefined && Object.hasOwn(modifiers, platform) ? platform : detected
+  const active = {
+    alt,
+    ctrl: ctrl || (mod && resolved !== 'apple'),
+    meta: meta || (mod && resolved === 'apple'),
+    shift,
+  }
 
   return (
     <kbd {...attributes} {...styles.kbd({ className, size, style: props.style, vars })}>
-      {modifiers.map(
-        ([key, glyph, name]) =>
+      {modifiers[resolved].map(
+        ([key, label, name]) =>
           active[key] && (
             <span key={key}>
-              <span aria-hidden="true">{glyph}</span>
+              <span aria-hidden="true">{label}</span>
               <span {...styles.hidden()}>{name} </span>
             </span>
           ),
@@ -49,13 +96,22 @@ export function Kbd(props: Kbd.Props) {
 export namespace Kbd {
   export type Props = ComponentPropsWithRef<'kbd'> &
     zyzz.Props.Variants<typeof styles.kbd> & {
-      /** Adds `⌥`, read as `Option`. */
+      /** Adds `⌥` (Option) on Apple platforms and Alt elsewhere. */
       alt?: boolean | undefined
-      /** Adds `⌃`, read as `Control`. */
+      /** Adds `⌃` (Control) on Apple platforms and Ctrl elsewhere. */
       ctrl?: boolean | undefined
-      /** Adds `⌘`, read as `Command`. */
+      /** Adds `⌘` (Command) on Apple platforms, Win on Windows, and Super on Linux. */
       meta?: boolean | undefined
-      /** Adds `⇧`, read as `Shift`. */
+      /** Adds the primary shortcut modifier: `⌘` (Command) on Apple platforms and Ctrl elsewhere. */
+      mod?: boolean | undefined
+      /**
+       * Selects the modifier labels, names and order. Defaults to the browser's platform, read after
+       * hydration, and to `apple` on the server. Browsers on other platforms, such as Android or
+       * ChromeOS, use the `linux` names. Any other value, such as a raw `Sec-CH-UA-Platform` header,
+       * falls back to the default.
+       */
+      platform?: keyof typeof modifiers | undefined
+      /** Adds `⇧` (Shift) on Apple platforms and Shift elsewhere. */
       shift?: boolean | undefined
     }
 }

package/src/web/components/Menu.tsx

@@ -306,7 +306,7 @@ export namespace styles {
 
   export const groupLabel = style(
     {
-      color: 'gray.700',
+      color: 'gray.900',
       paddingBlock: '8',
       paddingInline: '12',
       typography: 'label.12',
@@ -424,7 +424,7 @@ export namespace styles {
 
   export const shortcut = style(
     {
-      color: 'gray.700',
+      color: 'gray.900',
       marginInlineStart: 'auto !custom',
       paddingInlineStart: '16',
       typography: 'label.13',

package/src/web/components/NumberField.tsx

@@ -206,7 +206,7 @@ namespace styles {
       padding: '0',
       textAlign: 'center',
       selectors: {
-        '&::placeholder': { color: 'gray.700' },
+        '&::placeholder': { color: 'gray.900' },
         '[data-typing] > &': { color: 'inherit !custom' },
       },
     },