@colixsystems/widget-sdk 0.214.0 → 0.218.0

package/README.md

@@ -83,7 +83,34 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.214.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.218.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.218.0
+
+**Host helpers for the app logo's dark-bar variant.** An app can now carry a second logo for dark navigation bars, stored beside the app logo as `themeConfig.appLogoDarkAssetId` / `appLogoDarkUrl`. Two helpers on `@colixsystems/widget-sdk/host` decide which one a bar draws, and both hosts ask them, so the rail, the drawer, the app header and the site header pick the same logo in the web Player and in the exported app:
+
+- `isDarkSurface({ surface, backdrop, textColor, theme })` — `true` when the bar reads as dark. Pass the colour the bar paints as `surface`; a see-through `#RRGGBBAA` is composited over `backdrop`, or over the page in `theme`, first. A bar that paints nothing passes the `textColor` authored to sit on it instead: light text names a dark backdrop.
+- `resolveAppLogo(logo, darkSurfaceLogo, onDark)` — the logo to draw. The variant is used only beside an app logo; it never stands in for a missing one.
+
+These are host-integration helpers, not something a widget imports. Nothing changes for widget authors.
+
+### What's new in 0.215.0 (contract 1.174.0)
+
+**A themed chip: `Chip`, `ChipGroup`, and the `chip` theme scope.** `<Chip label selected onPress />` draws a filter chip, tag or pill whose fill, text colour, border, corner radius and selected colours come from **Theme Settings > Chips** (`themeConfig.components.chip`), so every chip in an app matches on the web Player and in the exported app. Pass `selected` with `onPress` for a chip that toggles (keep the selection in your own state), `onRemove` for a trailing remove button, `icon` for a lucide glyph before the label, and `disabled` to switch it off. A long label truncates on one line. `label` is a string or a number; pass `numberOfLines={0}` to let it wrap instead. `<ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen.
+
+```jsx
+const [status, setStatus] = useState("open");
+<ChipGroup selection="single" accessibilityLabel="Status">
+  {["open", "done"].map((s) => (
+    <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />
+  ))}
+</ChipGroup>
+<Chip label="Design" icon="tag" onRemove={() => removeTag("Design")} />
+```
+
+Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state. Outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web, Space and Enter press a chip, and a single-choice group is one tab stop whose arrow keys move the choice. The remove control is its own button labelled `Remove <label>`; pass `removeAccessibilityLabel` with your translated text. `size` is `"md"` (default, a 44px touch target) or `"sm"` (a compact 28px chip for a dense toolbar); `variant` is `"filled"` (default) or `"outlined"`. Pass `background`, `textColor`, `borderColor`, `radius`, `selectedBackground` or `selectedTextColor` (hex colours) to override one chip; a fill set without its text colour gets the dark or light label that reads on it. Unthemed, a chip is a muted pill with no border, and the selected one takes the primary colour. A status nobody taps stays a `<Badge>`.
+
+A component scope can now name the SDK components that read it directly (`sdkComponents`) instead of binding widget style fields; `chip` is the first.
 
 ### What's new in 0.214.0 (contract 1.173.0)
 
@@ -2617,6 +2644,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
 - `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, single-choice picker and search box. Like `TextField` they follow the theme's `muted` scope (and `popover` for the Select's option sheet) and take `label`, `helper`, `error` and `disabled`. `Select` opens its options at screen level. Never hand-roll one from `Pressable` and `View`.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
+- `Chip`, `ChipGroup` — the themed filter chip, tag or pill. `<Chip label selected onPress onRemove disabled>` follows the theme's `chip` scope; `<ChipGroup>` spaces and wraps its chips and, with `selection="single"`, announces them as one choice. Never hand-roll a chip from `Pressable` + a pill radius.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 

package/dist/chip-roving.js

@@ -0,0 +1,63 @@
+// The single tab stop of a single-choice `<ChipGroup>`, for the web. The chips
+// register with their group, and the group names the one that holds the tab
+// stop: the picked chip, else the first enabled one. Native never runs this:
+// React Native maps `tabIndex` to focusability, with no arrow keys to match.
+
+import React from "react";
+
+function inDocumentOrder([, a], [, b]) {
+  const before = a.node.compareDocumentPosition(b.node) & 4;
+  return before ? -1 : 1;
+}
+
+function tabStopHolder(members) {
+  const live = [...members.entries()]
+    .filter(([, m]) => !m.disabled && m.node && typeof m.node.compareDocumentPosition === "function")
+    .sort(inDocumentOrder);
+  const holder = live.find(([, m]) => m.selected) || live[0];
+  return holder ? holder[0] : null;
+}
+
+/**
+ * The group's half: a registry of its choices and the id that holds the tab
+ * stop. Inactive (both values null) unless `active`.
+ *
+ * @returns {{ register: Function|null, holder: string|null }}
+ */
+export function useTabStopRegistry(active) {
+  const members = React.useRef(new Map());
+  const [holder, setHolder] = React.useState(null);
+  const recompute = React.useCallback(() => setHolder(tabStopHolder(members.current)), []);
+  const register = React.useCallback(
+    (id, member) => {
+      if (member) members.current.set(id, member);
+      else members.current.delete(id);
+      recompute();
+    },
+    [recompute],
+  );
+  // After every render of the group: a reorder changes which chip is first.
+  React.useEffect(() => {
+    if (active) recompute();
+  });
+  return active ? { register, holder } : { register: null, holder: null };
+}
+
+/**
+ * A choice's half: registers it and returns its `tabIndex`, or undefined when
+ * its group keeps no single tab stop. Until the group has answered, the picked
+ * chip holds the stop so the first paint already has one.
+ */
+export function useTabStop(group, { node, disabled, selected, enrolled }) {
+  const id = React.useId();
+  const register = enrolled && group ? group.register : null;
+  React.useEffect(() => {
+    if (!register) return undefined;
+    register(id, { node: node.current, disabled: !!disabled, selected });
+    return () => register(id, null);
+  }, [register, id, node, disabled, selected]);
+  if (!register) return undefined;
+  if (disabled) return -1;
+  const holds = group.holder === null ? selected : group.holder === id;
+  return holds ? 0 : -1;
+}

package/dist/chip-tokens.js

@@ -0,0 +1,141 @@
+// The values `<Chip>` paints with, resolved from the theme's `chip` component
+// scope. Platform-free, like tabs-tokens.js, so both hosts draw one chip from
+// the same numbers and tests can pin them without a renderer.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { readableInk } from "./readable-ink.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+export const CHIP_VARIANTS = Object.freeze(["filled", "outlined"]);
+export const DEFAULT_CHIP_VARIANT = "filled";
+
+// `md` is a full touch target; `sm` is the compact chip of a dense toolbar.
+export const CHIP_SIZES = Object.freeze({
+  sm: Object.freeze({ minHeight: 28, fontSize: "xs", iconSize: 12 }),
+  md: Object.freeze({ minHeight: 44, fontSize: "sm", iconSize: 16 }),
+});
+export const DEFAULT_CHIP_SIZE = "md";
+
+// How a group of chips announces: one choice, several, or plain actions.
+export const CHIP_SELECTIONS = Object.freeze(["none", "single", "multiple"]);
+
+// Per-chip overrides a widget may pass, named as the theme tokens are.
+export const CHIP_TOKEN_NAMES = Object.freeze([
+  "background",
+  "textColor",
+  "borderColor",
+  "radius",
+  "selectedBackground",
+  "selectedTextColor",
+]);
+
+function isSet(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function pick(overrides, scope, name) {
+  if (overrides && isSet(overrides[name])) return overrides[name];
+  if (scope && isSet(scope[name])) return scope[name];
+  return undefined;
+}
+
+export function chipVariant(variant) {
+  return CHIP_VARIANTS.includes(variant) ? variant : DEFAULT_CHIP_VARIANT;
+}
+
+/** Object.hasOwn, because an inherited key ("constructor") is truthy. */
+export function chipSize(size) {
+  return CHIP_SIZES[Object.hasOwn(CHIP_SIZES, size) ? size : DEFAULT_CHIP_SIZE];
+}
+
+/**
+ * The role a chip announces with. A chip told whether it is `selected` is a
+ * choice: a radio in a single-choice group, otherwise a checkbox. Both carry
+ * `aria-checked`, the one selected state web and native each announce.
+ *
+ * @param {{ selectable: boolean, pressable: boolean, selection?: string }} chip
+ * @returns {"radio"|"checkbox"|"button"|undefined}
+ */
+export function chipRole({ selectable, pressable, selection }) {
+  if (selectable) return selection === "single" ? "radio" : "checkbox";
+  return pressable ? "button" : undefined;
+}
+
+/** The role a group announces with; only a single-choice group has one. */
+export function chipGroupRole(selection) {
+  return selection === "single" ? "radiogroup" : undefined;
+}
+
+/**
+ * Resolve one chip: explicit override, then the theme's `chip` scope, then the
+ * variant's own defaults. Overrides pass the contract's bounds, so a bad prop
+ * cannot reach a native style unvalidated. A border is drawn only when a
+ * colour for it resolves, so an unthemed filled chip keeps its exact size.
+ * A fill chosen without its text colour gets the label that reads on it.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — CHIP_TOKEN_NAMES values, plus `variant`.
+ */
+export function resolveChipTokens(theme, overrides) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = base.colors || DEFAULT_THEME_TOKENS.colors;
+  const radii = base.radii || DEFAULT_THEME_TOKENS.radii;
+  const scope = base.components && base.components.chip;
+  const own = normaliseThemeComponents({ chip: overrides }).chip;
+  const outlined = chipVariant(overrides && overrides.variant) === "outlined";
+
+  const ownFill = pick(own, scope, "background");
+  const ownSelectedFill = pick(own, scope, "selectedBackground");
+  const idleInk = outlined ? colors.onSurface : colors.onSurfaceMuted;
+  return {
+    background: ownFill ?? (outlined ? colors.surface : colors.surfaceMuted),
+    textColor:
+      pick(own, scope, "textColor") ?? (ownFill ? readableInk(ownFill, colors.surface) : idleInk),
+    borderColor: pick(own, scope, "borderColor") ?? (outlined ? colors.border : undefined),
+    radius: pick(own, scope, "radius") ?? radii.pill ?? DEFAULT_THEME_TOKENS.radii.pill,
+    selectedBackground: ownSelectedFill ?? colors.primary,
+    selectedTextColor:
+      pick(own, scope, "selectedTextColor") ??
+      (ownSelectedFill ? readableInk(ownSelectedFill, colors.surface) : colors.onPrimary),
+  };
+}
+
+/** The fill, ink and edge of one chip in its current state. */
+export function chipPaint(tokens, selected) {
+  const paint = {
+    backgroundColor: selected ? tokens.selectedBackground : tokens.background,
+    color: selected ? tokens.selectedTextColor : tokens.textColor,
+    borderRadius: tokens.radius,
+  };
+  if (tokens.borderColor === undefined) return paint;
+  // A selected chip's edge is clear, so the fill beneath shows through it: a
+  // translucent fill painted again as the border would draw a darker ring.
+  return {
+    ...paint,
+    borderWidth: 1,
+    borderColor: selected ? "transparent" : tokens.borderColor,
+  };
+}
+
+/**
+ * What each `chip` token resolves to while unset, keyed by token name, so the
+ * Studio can preview the default each control would replace. Each is resolved
+ * with only that token removed, since a text colour follows the fill beside
+ * it. No border colour: a chip with none set draws no border.
+ *
+ * @param {object} theme — the resolved workspace theme.
+ */
+export function chipScopeDefaults(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const scope = (base.components && base.components.chip) || {};
+  const out = {};
+  for (const name of CHIP_TOKEN_NAMES) {
+    const without = { ...scope, [name]: undefined };
+    const value = resolveChipTokens({ ...base, components: { ...base.components, chip: without } })[name];
+    if (value !== undefined) out[name] = value;
+  }
+  // A pill radius is past the token's range; its ceiling draws the same pill.
+  out.radius = Math.min(out.radius, CONTRACT.themeComponents.chip.tokens.radius.max);
+  return out;
+}

package/dist/chip-view.js

@@ -0,0 +1,324 @@
+// The ONE implementation behind the `<Chip>` and `<ChipGroup>` SDK components.
+// The platform bindings (`chip.js` / `chip.native.js`) differ only in where
+// the primitives come from, so the hosts cannot drift.
+//
+// Filter chips, tags and pills were hand-built per widget, each with its own
+// radius, padding and selected colour. This one reads the theme's `chip` scope.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import {
+  CHIP_SELECTIONS,
+  chipGroupRole,
+  chipPaint,
+  chipRole,
+  chipSize,
+  resolveChipTokens,
+} from "./chip-tokens.js";
+import { useTabStop, useTabStopRegistry } from "./chip-roving.js";
+
+const h = React.createElement;
+const DISABLED_OPACITY = 0.5;
+// react-native-web ignores hitSlop, so the remove target has real width;
+// native honours it, so there the target also reaches a full touch size.
+const REMOVE_TARGET_MIN_WIDTH = 32;
+const TOUCH_TARGET = 44;
+const ARROW_STEP = Object.freeze({ ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 });
+// Outside a group nothing says how close the next row is, so stay small.
+const UNGROUPED_ROW_GAP = 4;
+
+function plainLabel(label) {
+  if (typeof label === "number" && Number.isFinite(label)) return String(label);
+  return typeof label === "string" ? label : "";
+}
+
+function shapeStyle({ dims, surface, grouped, disabled }) {
+  return {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    // A long label truncates inside its row instead of pushing past it.
+    flexShrink: 1,
+    minWidth: 0,
+    maxWidth: "100%",
+    minHeight: dims.minHeight,
+    ...surface,
+    // Alone in a column it hugs its label; a group aligns its own chips.
+    ...(grouped ? null : { alignSelf: "flex-start" }),
+    ...(disabled ? { opacity: DISABLED_OPACITY } : null),
+  };
+}
+
+function bodyStyle(spacing, removable) {
+  return {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: spacing.xs,
+    flexShrink: 1,
+    minWidth: 0,
+    paddingVertical: spacing.xs,
+    paddingStart: spacing.sm,
+    // The remove button owns the trailing inset when there is one.
+    paddingEnd: removable ? 0 : spacing.sm,
+  };
+}
+
+// Read when a key is pressed, so the arrows follow the order on screen.
+function enabledRadios(node) {
+  return Array.from(node.querySelectorAll('[role="radio"]')).filter(
+    (el) => el.getAttribute("aria-disabled") !== "true",
+  );
+}
+
+// The radiogroup pattern: an arrow moves focus to the next choice and picks it.
+function moveChoice(event, step) {
+  const group = event.currentTarget.closest('[role="radiogroup"]');
+  const radios = group ? enabledRadios(group) : [];
+  const at = radios.indexOf(event.currentTarget);
+  if (at < 0 || radios.length < 2) return;
+  event.preventDefault();
+  const next = radios[(at + step + radios.length) % radios.length];
+  next.focus();
+  next.click();
+}
+
+// Web only; native fires no key events. react-native-web presses on Enter for
+// every role but on Space for buttons alone, so a choice handles Space itself.
+function choiceKeyHandler(onPress, roving) {
+  return (event) => {
+    // A held key must not toggle at repeat rate, nor Alt+Arrow lose its meaning.
+    if (event.repeat || event.altKey || event.ctrlKey || event.metaKey) return;
+    if (event.key === " " || event.key === "Spacebar") {
+      event.preventDefault();
+      onPress();
+    } else if (roving && ARROW_STEP[event.key]) {
+      moveChoice(event, ARROW_STEP[event.key]);
+    }
+  };
+}
+
+// accessibilityRole + aria-*: the pair that announces on both hosts.
+function pressProps({ onPress, disabled, role, name }) {
+  return {
+    onPress,
+    disabled: !!disabled,
+    accessibilityRole: role,
+    accessibilityLabel: name,
+    "aria-disabled": !!disabled,
+  };
+}
+
+function choiceProps({ onPress, disabled, selected, roving, tabIndex }) {
+  return {
+    "aria-checked": selected,
+    ...(disabled ? null : { onKeyDown: choiceKeyHandler(onPress, roving) }),
+    ...(tabIndex === undefined ? null : { tabIndex }),
+  };
+}
+
+// Never past half the gap to the next row: a tap there belongs to that row.
+function removeHitSlop(dims, rowGap) {
+  const wanted = Math.max(0, (TOUCH_TARGET - dims.minHeight) / 2);
+  const vertical = Math.min(wanted, rowGap / 2);
+  return { top: vertical, bottom: vertical, right: (TOUCH_TARGET - REMOVE_TARGET_MIN_WIDTH) / 2 };
+}
+
+// With no clip on the chip, each half rounds its own outer corners so a focus
+// outline follows the pill.
+function startCorners(radius) {
+  return { borderTopStartRadius: radius, borderBottomStartRadius: radius };
+}
+
+function endCorners(radius) {
+  return { borderTopEndRadius: radius, borderBottomEndRadius: radius };
+}
+
+function labelStyle({ typography, dims, selected, ink }) {
+  return {
+    flexShrink: 1,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.sizes[dims.fontSize],
+    fontWeight: selected ? "600" : "500",
+    color: ink,
+  };
+}
+
+/**
+ * Bind the shared chip to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ * @param {{ web?: boolean }} [host] — `web` turns on the single tab stop.
+ */
+export function makeChip(rn, host) {
+  const { View, Text, Pressable } = rn;
+  const rovingTabStop = !!(host && host.web);
+  const GroupContext = React.createContext(null);
+
+  function RemoveButton({ onRemove, disabled, label, spacing, dims, ink, radius, rowGap, testID }) {
+    return h(
+      Pressable,
+      {
+        ...pressProps({ onPress: onRemove, disabled, role: "button", name: label }),
+        testID,
+        hitSlop: removeHitSlop(dims, rowGap),
+        style: {
+          ...endCorners(radius),
+          alignSelf: "stretch",
+          alignItems: "center",
+          justifyContent: "center",
+          minWidth: REMOVE_TARGET_MIN_WIDTH,
+          paddingStart: spacing.xs,
+          paddingEnd: spacing.sm,
+        },
+      },
+      h(Icon, { name: "x", size: dims.iconSize, color: ink }),
+    );
+  }
+
+  function Chip({
+    label,
+    icon,
+    selected,
+    onPress,
+    onRemove,
+    disabled,
+    variant,
+    size,
+    numberOfLines = 1,
+    theme: explicitTheme,
+    accessibilityLabel,
+    removeAccessibilityLabel,
+    style,
+    testID,
+    ...overrides
+  }) {
+    const group = React.useContext(GroupContext);
+    const hostTheme = useHostTheme();
+    // A Studio preview renders outside a widget context, so it passes its own.
+    const theme = explicitTheme || (group && group.theme) || hostTheme || DEFAULT_THEME_TOKENS;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const dims = chipSize(size);
+    const isSelected = selected === true;
+    const tokens = resolveChipTokens(theme, { ...overrides, variant });
+    const { color: ink, ...surface } = chipPaint(tokens, isSelected);
+    const pressable = typeof onPress === "function";
+    const removable = typeof onRemove === "function";
+    const selection = group ? group.selection : "none";
+    // In a choice group every pressable chip is a choice, picked or not.
+    const selectable = pressable && (typeof selected === "boolean" || selection !== "none");
+    const roving = selectable && selection === "single";
+    const body = React.useRef(null);
+    const tabIndex = useTabStop(group, {
+      node: body,
+      disabled,
+      selected: isSelected,
+      enrolled: roving,
+    });
+
+    const shape = shapeStyle({ dims, surface, grouped: !!group, disabled });
+    const bodyLayout = bodyStyle(spacing, removable);
+    const content = [
+      icon ? h(Icon, { key: "icon", name: icon, size: dims.iconSize, color: ink }) : null,
+      h(
+        Text,
+        {
+          key: "label",
+          // Zero lifts the limit, so a long label wraps instead.
+          numberOfLines:
+            Number.isInteger(numberOfLines) && numberOfLines > 0 ? numberOfLines : undefined,
+          style: labelStyle({ typography, dims, selected: isSelected, ink }),
+        },
+        label,
+      ),
+    ];
+    const interaction = pressable
+      ? {
+          ...pressProps({
+            onPress,
+            disabled,
+            role: chipRole({ selectable, pressable, selection }),
+            name: accessibilityLabel || plainLabel(label) || undefined,
+          }),
+          ...(selectable
+            ? choiceProps({ onPress, disabled, selected: isSelected, roving, tabIndex })
+            : null),
+          ref: body,
+        }
+      : null;
+    const Body = pressable ? Pressable : View;
+
+    if (!removable) {
+      return h(Body, { ...interaction, style: [shape, bodyLayout, style], testID }, ...content);
+    }
+    return h(
+      View,
+      { style: [shape, style], testID },
+      h(
+        Body,
+        {
+          ...interaction,
+          style: [bodyLayout, startCorners(tokens.radius), { minHeight: dims.minHeight }],
+          testID: testID ? `${testID}-body` : undefined,
+        },
+        ...content,
+      ),
+      h(RemoveButton, {
+        onRemove,
+        disabled,
+        label: removeAccessibilityLabel || `Remove ${plainLabel(label)}`.trim(),
+        spacing,
+        dims,
+        ink,
+        radius: tokens.radius,
+        rowGap: group ? group.rowGap : UNGROUPED_ROW_GAP,
+        testID: testID ? `${testID}-remove` : undefined,
+      }),
+    );
+  }
+  Chip.displayName = "Chip";
+
+  function ChipGroup({
+    children,
+    selection,
+    gap,
+    theme: explicitTheme,
+    accessibilityLabel,
+    style,
+    testID,
+  }) {
+    const hostTheme = useHostTheme();
+    const theme = explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const mode = CHIP_SELECTIONS.includes(selection) ? selection : "none";
+    const rowGap = typeof gap === "number" && Number.isFinite(gap) && gap >= 0 ? gap : spacing.xs;
+    const { register, holder } = useTabStopRegistry(rovingTabStop && mode === "single");
+    const context = React.useMemo(
+      () => ({ selection: mode, theme: explicitTheme, rowGap, register, holder }),
+      [mode, explicitTheme, rowGap, register, holder],
+    );
+    return h(
+      GroupContext.Provider,
+      { value: context },
+      h(
+        View,
+        {
+          accessibilityRole: chipGroupRole(mode),
+          accessibilityLabel,
+          testID,
+          style: [
+            { flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: rowGap },
+            style,
+          ],
+        },
+        children,
+      ),
+    );
+  }
+  ChipGroup.displayName = "ChipGroup";
+
+  return { Chip, ChipGroup };
+}

package/dist/chip.js

@@ -0,0 +1,8 @@
+// `<Chip>` / `<ChipGroup>` (web). Binds ./chip-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier. Only the web keeps a single
+// tab stop per single-choice group.
+
+import * as ReactNative from "react-native-web";
+import { makeChip } from "./chip-view.js";
+
+export const { Chip, ChipGroup } = makeChip(ReactNative, { web: true });

package/dist/chip.native.js

@@ -0,0 +1,7 @@
+// `<Chip>` / `<ChipGroup>` (native). Binds ./chip-view.js to React Native's own
+// primitives; only the import differs from ./chip.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeChip } from "./chip-view.js";
+
+export const { Chip, ChipGroup } = makeChip({ View, Text, Pressable });

package/dist/contract.cjs

@@ -745,6 +745,22 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Filter chips, tags and pills: `<Chip>` reads this scope directly, so it
+  // names the SDK component it styles and binds no widget field. No uiDefault:
+  // an unset text colour follows its fill, so the default is derived.
+  chip: Object.freeze({
+    label: "Chips",
+    sdkComponents: Object.freeze(["Chip"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      selectedBackground: Object.freeze({ type: "color" }),
+      selectedTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -3073,6 +3089,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chip",
+    description:
+      'Themed chip. `<ChipGroup selection="single">{STATUSES.map((s) => <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />)}</ChipGroup>`. THE way to build filter chips, tags and pills: anything small, rounded and tappable that selects, filters or can be removed. ONE facet with up to five options may be a single-choice `<ChipGroup>` of all its options; several facets, or a longer option list, go in the filter toolbar, where only the ACTIVE filters show as removable chips. Its fill, text colour, border, corner radius and selected colours come from the app\'s chip look (Theme Settings > Chips), so every chip in the app matches. Never hand-roll one from `Pressable` + `radii.pill` + a fill. A display-only STATE (Active, Paid, Overdue) is a `<Badge>`, not a chip. Props: `label` (a string or a number; it truncates on one line instead of breaking the row, or pass `numberOfLines={0}` to let it wrap), `icon` (optional lucide name before the label), `selected` (boolean; pass it together with `onPress` for a chip that toggles, and keep the selection in your own state), `onPress`, `onRemove` (adds a trailing x button, e.g. an active filter or a tag the user can drop; it is a separate button from `onPress`), `disabled`, `size` ("md" default, a full 44px touch target: use it on a narrow screen | "sm", a compact 28px chip for a medium or wide toolbar), `variant` ("filled" default | "outlined", a bordered chip on the surface), `accessibilityLabel`, `removeAccessibilityLabel` (default "Remove <label>"; pass your translated text), `style`, `testID`, and the overrides `background`, `textColor`, `borderColor`, `radius`, `selectedBackground`, `selectedTextColor` (hex colours; leave them unset so the app\'s chip look applies; a fill set without its text colour gets the dark or light label that reads on it). Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state; outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web a single-choice group is one tab stop and the arrow keys move the choice.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ChipGroup",
+    description:
+      'Wrapping row of `<Chip>`s. `<ChipGroup selection="multiple" accessibilityLabel="Tags">…</ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen, so never lay chips out in a hand-rolled `flexWrap` row. Props: `selection` ("none" default | "single", one choice at a time, so its chips are radios | "multiple", any number of choices), `gap` (px between chips; defaults to the theme\'s `spacing.xs`), `accessibilityLabel`, `style`, `testID`. It only lays out and announces: the selected value lives in your state and each chip gets its own `selected` and `onPress`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Card",
     description:
@@ -5671,7 +5701,13 @@ const CONTRACT = deepFreeze({
   //    seen online / today / in 7 or 30 days through the new
   //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
   //    `sort: "newest"` for an admin's "who joined" list.
-  version: "1.173.0",
+  // 1.174.0: additive (sc-10926) — the `chip` component scope (background,
+  //    text colour, border colour, radius, selected background, selected text
+  //    colour) and the `Chip` / `ChipGroup` primitives that read it. The scope
+  //    binds no widget style fields: the component reads it on both hosts,
+  //    which a scope now states as `sdkComponents`.
+  //    Additive: an unthemed chip is the muted pill widgets drew by hand.
+  version: "1.174.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -745,6 +745,22 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Filter chips, tags and pills: `<Chip>` reads this scope directly, so it
+  // names the SDK component it styles and binds no widget field. No uiDefault:
+  // an unset text colour follows its fill, so the default is derived.
+  chip: Object.freeze({
+    label: "Chips",
+    sdkComponents: Object.freeze(["Chip"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      selectedBackground: Object.freeze({ type: "color" }),
+      selectedTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -3073,6 +3089,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chip",
+    description:
+      'Themed chip. `<ChipGroup selection="single">{STATUSES.map((s) => <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />)}</ChipGroup>`. THE way to build filter chips, tags and pills: anything small, rounded and tappable that selects, filters or can be removed. ONE facet with up to five options may be a single-choice `<ChipGroup>` of all its options; several facets, or a longer option list, go in the filter toolbar, where only the ACTIVE filters show as removable chips. Its fill, text colour, border, corner radius and selected colours come from the app\'s chip look (Theme Settings > Chips), so every chip in the app matches. Never hand-roll one from `Pressable` + `radii.pill` + a fill. A display-only STATE (Active, Paid, Overdue) is a `<Badge>`, not a chip. Props: `label` (a string or a number; it truncates on one line instead of breaking the row, or pass `numberOfLines={0}` to let it wrap), `icon` (optional lucide name before the label), `selected` (boolean; pass it together with `onPress` for a chip that toggles, and keep the selection in your own state), `onPress`, `onRemove` (adds a trailing x button, e.g. an active filter or a tag the user can drop; it is a separate button from `onPress`), `disabled`, `size` ("md" default, a full 44px touch target: use it on a narrow screen | "sm", a compact 28px chip for a medium or wide toolbar), `variant` ("filled" default | "outlined", a bordered chip on the surface), `accessibilityLabel`, `removeAccessibilityLabel` (default "Remove <label>"; pass your translated text), `style`, `testID`, and the overrides `background`, `textColor`, `borderColor`, `radius`, `selectedBackground`, `selectedTextColor` (hex colours; leave them unset so the app\'s chip look applies; a fill set without its text colour gets the dark or light label that reads on it). Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state; outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web a single-choice group is one tab stop and the arrow keys move the choice.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ChipGroup",
+    description:
+      'Wrapping row of `<Chip>`s. `<ChipGroup selection="multiple" accessibilityLabel="Tags">…</ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen, so never lay chips out in a hand-rolled `flexWrap` row. Props: `selection` ("none" default | "single", one choice at a time, so its chips are radios | "multiple", any number of choices), `gap` (px between chips; defaults to the theme\'s `spacing.xs`), `accessibilityLabel`, `style`, `testID`. It only lays out and announces: the selected value lives in your state and each chip gets its own `selected` and `onPress`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Card",
     description:
@@ -5667,7 +5697,13 @@ const CONTRACT = deepFreeze({
   //    seen online / today / in 7 or 30 days through the new
   //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
   //    `sort: "newest"` for an admin's "who joined" list.
-  version: "1.173.0",
+  // 1.174.0: additive (sc-10926) — the `chip` component scope (background,
+  //    text colour, border colour, radius, selected background, selected text
+  //    colour) and the `Chip` / `ChipGroup` primitives that read it. The scope
+  //    binds no widget style fields: the component reads it on both hosts,
+  //    which a scope now states as `sdkComponents`.
+  //    Additive: an unthemed chip is the muted pill widgets drew by hand.
+  version: "1.174.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -45,6 +45,12 @@ export function normaliseThemeComponents(raw: unknown): ThemeComponents;
  */
 export function bannerScopeDefaults(theme: unknown): Record<string, string | number>;
 
+/**
+ * What each token of the `chip` component scope resolves to while unset,
+ * keyed by token name: the values `<Chip>` paints an unthemed app with.
+ */
+export function chipScopeDefaults(theme: unknown): Record<string, string | number>;
+
 /**
  * The theme a surface painting `backgroundColor` hands its subtree: surface
  * tokens derived for that fill, and any type tier whose own ink cannot be read
@@ -391,6 +397,25 @@ export interface TopBarTokens {
  */
 export function resolveTopBarTokens(theme: unknown): TopBarTokens;
 
+/**
+ * Whether a chrome surface reads as dark. Pass the colour the bar paints
+ * (`#RRGGBBAA` is composited over `backdrop`, else over the page in `theme`),
+ * or, for a bar that paints nothing, the colour of the text authored to sit on it.
+ */
+export function isDarkSurface(input?: {
+  surface?: string | null;
+  backdrop?: string | null;
+  textColor?: string | null;
+  theme?: unknown;
+} | null): boolean;
+
+/** The logo a surface draws: the dark-surface variant only beside an app logo. */
+export function resolveAppLogo<T>(
+  logo: T | null | undefined,
+  darkSurfaceLogo: T | null | undefined,
+  onDark: boolean,
+): T | null;
+
 /** sc-8023 — the arrangeable contents of the sidebar layout's TOP STRIPE: the
  *  row across the top of the content, outside the panel and above it. */
 export type TopStripeSlot = "back" | "menu" | "brand" | "notifications";

package/dist/host.js

@@ -51,6 +51,9 @@ export { surfaceAwareTheme } from "./surface-theme.js";
 // the Expo export rendering the same notification (CLAUDE.md §8).
 // The dialog's resolved look, for the Studio's Design > Components > Dialogs preview.
 export { resolveModalTokens, modalScopeDefaults } from "./modal-tokens.js";
+// What each `chip` scope token resolves to while unset, for the Studio's
+// Design page to preview beside its controls.
+export { chipScopeDefaults } from "./chip-tokens.js";
 
 export {
   createToastController,
@@ -107,6 +110,8 @@ export {
   resolveSidebarUnfold,
   resolveLocalNavModel,
   drawsLocalNavAnywhere,
+  isDarkSurface,
+  resolveAppLogo,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

package/dist/index.d.ts

@@ -3917,6 +3917,73 @@ export const Banner: (props: {
   testID?: string;
 }) => any;
 
+export type ChipVariant = "filled" | "outlined";
+export type ChipSize = "sm" | "md";
+export type ChipSelection = "none" | "single" | "multiple";
+
+/**
+ * Themed filter chip, tag or pill. Its fill, text colour, border, corner radius
+ * and selected colours come from the theme's `chip` scope, so every chip in the
+ * app matches. Pass `selected` with `onPress` for a chip that toggles. Inside a
+ * `<ChipGroup>` with a `selection` every pressable chip is a choice (a radio
+ * when single, otherwise a checkbox); outside one, a boolean `selected` makes
+ * it a checkbox. `onRemove` adds a trailing remove button.
+ *
+ * @example
+ *   <Chip label="Open" selected={status === "open"} onPress={() => setStatus("open")} />
+ *   <Chip label="Design" onRemove={() => removeTag("Design")} />
+ */
+export const Chip: (props: {
+  label: string | number;
+  /** Lines the label may take before it truncates; 0 lets it wrap. Default 1. */
+  numberOfLines?: number;
+  /** A lucide icon name, drawn before the label. */
+  icon?: string;
+  selected?: boolean;
+  onPress?: () => void;
+  onRemove?: () => void;
+  disabled?: boolean;
+  /** `md` (default) is a 44px touch target; `sm` is a compact 28px chip. */
+  size?: ChipSize;
+  variant?: ChipVariant;
+  /**
+   * Hex colour overrides; leave unset so the theme's chip look applies. A fill
+   * set without its text colour gets the dark or light label that reads on it.
+   */
+  background?: string;
+  textColor?: string;
+  borderColor?: string;
+  radius?: number;
+  selectedBackground?: string;
+  selectedTextColor?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  accessibilityLabel?: string;
+  /** Defaults to "Remove <label>"; pass translated text. */
+  removeAccessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/**
+ * Wrapping row of `<Chip>`s: spaces them and wraps onto the next line when the
+ * row is full. `selection` sets how the chips announce and, on the web, how
+ * the keyboard reaches them (a single-choice group is one tab stop whose
+ * arrow keys move the choice). It holds no state: the selected
+ * value stays in your own state.
+ */
+export const ChipGroup: (props: {
+  children?: ReactNode;
+  selection?: ChipSelection;
+  /** Px between chips; defaults to the theme's `spacing.xs`. */
+  gap?: number;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
 /**
  * Themed collapsible sections. The surface comes from the theme's `card`
  * scope and the headers and dividers from its `list` scope, so every

package/dist/index.js

@@ -285,6 +285,8 @@ export { Banner } from "./banner.js";
 export { Modal } from "./modal.js";
 // The standard confirmation, a preset of `<Modal>` and `<Button>`.
 export { ConfirmDialog } from "./confirm-dialog.js";
+// Themed filter chips, tags and pills; follow the theme's `chip` scope.
+export { Chip, ChipGroup } from "./chip.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -278,6 +278,8 @@ export { Banner } from "./banner.native.js";
 export { Modal } from "./modal.native.js";
 // The standard confirmation, a preset of `<Modal>` and `<Button>`.
 export { ConfirmDialog } from "./confirm-dialog.native.js";
+// Themed filter chips, tags and pills; follow the theme's `chip` scope.
+export { Chip, ChipGroup } from "./chip.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/navigation.cjs

@@ -535,6 +535,33 @@ function resolveTopStripeLayout(theme) {
   };
 }
 
+// Whether a chrome surface reads as dark — asked for the app logo's variant
+// and for the status-bar glyphs, so the two can never disagree about a bar.
+// A see-through `surface` is judged by its blend with what is behind it: the
+// given `backdrop`, else the page in `theme`. A bar that paints nothing passes
+// `textColor` instead: light text was authored for a dark backdrop.
+function isDarkSurface(input) {
+  const { surface, backdrop, textColor, theme } = isPlainObject(input) ? input : {};
+  if (isHexColor(surface)) {
+    const alpha = surface.length === 9 ? parseInt(surface.slice(7), 16) / 255 : 1;
+    const behind = isHexColor(backdrop)
+      ? backdrop
+      : chromeSurface(isPlainObject(theme) ? theme : {});
+    const seen = alpha < 1 ? mixHex(behind, surface.slice(0, 7), alpha) : surface;
+    return readableTextColor(seen, "dark", "light") === "light";
+  }
+  if (isHexColor(textColor)) {
+    return readableTextColor(textColor, "dark", "light") === "dark";
+  }
+  return false;
+}
+
+// The dark-surface logo is a VARIANT of the app logo: it never stands alone.
+function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
+  if (!logo) return null;
+  return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
+}
+
 const TAB_ALIGNMENTS = ["left", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
@@ -817,4 +844,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere, isDarkSurface, resolveAppLogo };

package/dist/navigation.js

@@ -526,6 +526,33 @@ export function resolveTopStripeLayout(theme) {
   };
 }
 
+// Whether a chrome surface reads as dark — asked for the app logo's variant
+// and for the status-bar glyphs, so the two can never disagree about a bar.
+// A see-through `surface` is judged by its blend with what is behind it: the
+// given `backdrop`, else the page in `theme`. A bar that paints nothing passes
+// `textColor` instead: light text was authored for a dark backdrop.
+export function isDarkSurface(input) {
+  const { surface, backdrop, textColor, theme } = isPlainObject(input) ? input : {};
+  if (isHexColor(surface)) {
+    const alpha = surface.length === 9 ? parseInt(surface.slice(7), 16) / 255 : 1;
+    const behind = isHexColor(backdrop)
+      ? backdrop
+      : chromeSurface(isPlainObject(theme) ? theme : {});
+    const seen = alpha < 1 ? mixHex(behind, surface.slice(0, 7), alpha) : surface;
+    return readableTextColor(seen, "dark", "light") === "light";
+  }
+  if (isHexColor(textColor)) {
+    return readableTextColor(textColor, "dark", "light") === "dark";
+  }
+  return false;
+}
+
+// The dark-surface logo is a VARIANT of the app logo: it never stands alone.
+export function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
+  if (!logo) return null;
+  return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
+}
+
 const TAB_ALIGNMENTS = ["left", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.214.0",
+  "version": "0.218.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -745,6 +745,22 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Filter chips, tags and pills: `<Chip>` reads this scope directly, so it
+  // names the SDK component it styles and binds no widget field. No uiDefault:
+  // an unset text colour follows its fill, so the default is derived.
+  chip: Object.freeze({
+    label: "Chips",
+    sdkComponents: Object.freeze(["Chip"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      selectedBackground: Object.freeze({ type: "color" }),
+      selectedTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -3073,6 +3089,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chip",
+    description:
+      'Themed chip. `<ChipGroup selection="single">{STATUSES.map((s) => <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />)}</ChipGroup>`. THE way to build filter chips, tags and pills: anything small, rounded and tappable that selects, filters or can be removed. ONE facet with up to five options may be a single-choice `<ChipGroup>` of all its options; several facets, or a longer option list, go in the filter toolbar, where only the ACTIVE filters show as removable chips. Its fill, text colour, border, corner radius and selected colours come from the app\'s chip look (Theme Settings > Chips), so every chip in the app matches. Never hand-roll one from `Pressable` + `radii.pill` + a fill. A display-only STATE (Active, Paid, Overdue) is a `<Badge>`, not a chip. Props: `label` (a string or a number; it truncates on one line instead of breaking the row, or pass `numberOfLines={0}` to let it wrap), `icon` (optional lucide name before the label), `selected` (boolean; pass it together with `onPress` for a chip that toggles, and keep the selection in your own state), `onPress`, `onRemove` (adds a trailing x button, e.g. an active filter or a tag the user can drop; it is a separate button from `onPress`), `disabled`, `size` ("md" default, a full 44px touch target: use it on a narrow screen | "sm", a compact 28px chip for a medium or wide toolbar), `variant` ("filled" default | "outlined", a bordered chip on the surface), `accessibilityLabel`, `removeAccessibilityLabel` (default "Remove <label>"; pass your translated text), `style`, `testID`, and the overrides `background`, `textColor`, `borderColor`, `radius`, `selectedBackground`, `selectedTextColor` (hex colours; leave them unset so the app\'s chip look applies; a fill set without its text colour gets the dark or light label that reads on it). Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state; outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web a single-choice group is one tab stop and the arrow keys move the choice.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ChipGroup",
+    description:
+      'Wrapping row of `<Chip>`s. `<ChipGroup selection="multiple" accessibilityLabel="Tags">…</ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen, so never lay chips out in a hand-rolled `flexWrap` row. Props: `selection` ("none" default | "single", one choice at a time, so its chips are radios | "multiple", any number of choices), `gap` (px between chips; defaults to the theme\'s `spacing.xs`), `accessibilityLabel`, `style`, `testID`. It only lays out and announces: the selected value lives in your state and each chip gets its own `selected` and `onPress`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Card",
     description:
@@ -5667,7 +5697,13 @@ const CONTRACT = deepFreeze({
   //    seen online / today / in 7 or 30 days through the new
   //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
   //    `sort: "newest"` for an admin's "who joined" list.
-  version: "1.173.0",
+  // 1.174.0: additive (sc-10926) — the `chip` component scope (background,
+  //    text colour, border colour, radius, selected background, selected text
+  //    colour) and the `Chip` / `ChipGroup` primitives that read it. The scope
+  //    binds no widget style fields: the component reads it on both hosts,
+  //    which a scope now states as `sdkComponents`.
+  //    Additive: an unthemed chip is the muted pill widgets drew by hand.
+  version: "1.174.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,