@grampro/kit 0.0.0-stage → 2.4.1

package/source/components/avatar/styles.css

@@ -0,0 +1,225 @@
+/*
+ * Avatar and AvatarGroup styles.
+ *
+ * The fallback colour comes from --av-hue-index, which the component sets from
+ * a hash of the name: the same person is the same colour everywhere, and the
+ * palette is generated rather than listed, so it follows a themed hue. Tokens
+ * read the shared --gbs-* variables when they are set on an ancestor (set them
+ * on :root to theme every component at once). Rules are unlayered: they beat a
+ * framework reset on specificity, and lose to anything you pass through
+ * `className`. With Tailwind v4, import this file after the framework and
+ * inside its components layer - see the README.
+ */
+
+.av-root,
+.av-group,
+.av-overflow {
+  --av-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --av-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --av-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --av-subtle: var(--gbs-subtle, light-dark(#f4f4f5, #1c1c20));
+  --av-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --av-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+  --av-warning: var(--gbs-warning, light-dark(#b45309, #fbbf24));
+  --av-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --av-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --av-size: 32px;
+  --av-font-size: 13px;
+  --av-hue-index: 0;
+  /* Eight hues, 45° apart, starting at the blue end. */
+  --av-hue: calc(210 + var(--av-hue-index) * 45);
+
+  color-scheme: inherit;
+}
+
+:where(.dark, [data-theme="dark"]) :is(.av-root, .av-group, .av-overflow) {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) :is(.av-root, .av-group, .av-overflow) {
+  color-scheme: light;
+}
+
+:where(.av-root, .av-group) *,
+:where(.av-root, .av-group) *::before,
+:where(.av-root, .av-group) *::after {
+  box-sizing: border-box;
+}
+
+.av-root {
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: var(--av-size);
+  height: var(--av-size);
+  border-radius: 50%;
+  background: var(--av-subtle);
+  font-size: var(--av-font-size);
+  font-weight: 600;
+  line-height: 1;
+  overflow: hidden;
+  user-select: none;
+  vertical-align: middle;
+}
+.av-root[data-shape="square"] {
+  border-radius: var(--av-radius);
+  overflow: visible;
+}
+.av-root[data-shape="square"] .av-image,
+.av-root[data-shape="square"] .av-fallback {
+  border-radius: var(--av-radius);
+}
+
+.av-root[data-size="xs"] {
+  --av-size: 20px;
+  --av-font-size: 10px;
+}
+.av-root[data-size="sm"] {
+  --av-size: 24px;
+  --av-font-size: 11px;
+}
+.av-root[data-size="lg"] {
+  --av-size: 40px;
+  --av-font-size: 15px;
+}
+.av-root[data-size="xl"] {
+  --av-size: 56px;
+  --av-font-size: 20px;
+}
+
+.av-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* `oklch` keeps every hue at the same lightness, so no one person's initials
+   come out harder to read than another's — which is what a list of hand-picked
+   hex pairs always ends up doing. */
+.av-fallback {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  background: oklch(from light-dark(oklch(0.93 0.05 0), oklch(0.32 0.06 0)) l c var(--av-hue));
+  color: oklch(from light-dark(oklch(0.42 0.13 0), oklch(0.88 0.1 0)) l c var(--av-hue));
+  text-transform: uppercase;
+}
+.av-fallback > svg {
+  width: 60%;
+  height: 60%;
+}
+
+.av-status {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: 30%;
+  height: 30%;
+  min-width: 8px;
+  min-height: 8px;
+  border: 2px solid var(--av-bg);
+  border-radius: 50%;
+  background: var(--av-muted);
+}
+.av-root[data-shape="square"] .av-status {
+  right: -2px;
+  bottom: -2px;
+}
+.av-status[data-status="online"] {
+  background: var(--av-success);
+}
+.av-status[data-status="away"] {
+  background: var(--av-warning);
+}
+.av-status[data-status="busy"] {
+  background: var(--av-danger);
+}
+
+/* ---------------------------------------------------------------- group */
+
+.av-group {
+  display: inline-flex;
+  align-items: center;
+  vertical-align: middle;
+}
+/* Each face overlaps the one before and is ringed in the page colour, so the
+   stack reads as separate people rather than one smear. */
+.av-group > * {
+  margin-inline-start: calc(var(--av-size) / -4);
+  box-shadow: 0 0 0 2px var(--av-bg);
+}
+.av-group > *:first-child {
+  margin-inline-start: 0;
+}
+
+.av-overflow {
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: var(--av-size);
+  height: var(--av-size);
+  border-radius: 50%;
+  background: var(--av-subtle);
+  /* Muted grey clears 4.5:1 on the page background but only reaches 4.39:1
+     on this one, so the count moves a step towards the text colour. */
+  color: color-mix(in oklab, var(--av-muted) 65%, var(--av-fg));
+  font-size: calc(var(--av-font-size) - 1px);
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+.av-overflow[data-shape="square"] {
+  border-radius: var(--av-radius);
+}
+.av-group[data-size="xs"],
+.av-overflow[data-size="xs"] {
+  --av-size: 20px;
+  --av-font-size: 10px;
+}
+.av-group[data-size="sm"],
+.av-overflow[data-size="sm"] {
+  --av-size: 24px;
+  --av-font-size: 11px;
+}
+.av-group[data-size="lg"],
+.av-overflow[data-size="lg"] {
+  --av-size: 40px;
+  --av-font-size: 15px;
+}
+.av-group[data-size="xl"],
+.av-overflow[data-size="xl"] {
+  --av-size: 56px;
+  --av-font-size: 20px;
+}
+/* The group's size reaches the avatars inside it, unless one sets its own. */
+.av-group[data-size="xs"] .av-root:not([data-size]) {
+  --av-size: 20px;
+  --av-font-size: 10px;
+}
+.av-group[data-size="sm"] .av-root:not([data-size]) {
+  --av-size: 24px;
+  --av-font-size: 11px;
+}
+.av-group[data-size="lg"] .av-root:not([data-size]) {
+  --av-size: 40px;
+  --av-font-size: 15px;
+}
+.av-group[data-size="xl"] .av-root:not([data-size]) {
+  --av-size: 56px;
+  --av-font-size: 20px;
+}
+
+@media (forced-colors: active) {
+  .av-root,
+  .av-overflow {
+    border: 1px solid CanvasText;
+  }
+  .av-status {
+    border-color: Canvas;
+  }
+}

package/source/components/badge/README.md

@@ -0,0 +1,37 @@
+# Badge and Tag
+
+Short labels for React 19, styled to match the rest of the library. A **Badge**
+is static text — a status, a category, a count. A **Tag** is a chip the user can
+take off. No runtime dependencies besides React.
+
+```ts
+import { Badge, Tag } from "@/components/badge";
+import "@/components/badge/styles.css";
+```
+
+```tsx
+<Badge variant="success">Active</Badge>
+<Badge variant="danger" appearance="solid" count={128} />   {/* 99+ */}
+<Badge variant="warning" dot>Degraded</Badge>
+
+<Tag onRemove={() => remove("berlin")}>Berlin</Tag>
+```
+
+**Badge:** `children` or `count`, `variant` (`neutral` `accent` `success`
+`warning` `danger` `info`), `appearance` (`soft` `solid` `outline`), `size`
+(`sm` `md`), `max`, `showZero`, `formatValue`, `dot`, `icon`, `classNames`
+(`root` `dot` `icon` `label`), `ref`, and every `<span>` attribute.
+
+**Tag:** the same variants, plus `onRemove`, `label` (names the remove button
+when the children are not a plain string), `disabled`, `classNames` (`root`
+`icon` `label` `remove`), `localeText`.
+
+A badge with `count` renders nothing at all when the count is zero, unless
+`showZero` says otherwise: an empty counter is noise on the page and a spurious
+announcement in a screen reader.
+
+The remove button carries the tag's own text in its name — "Remove Berlin" —
+because a row of identical "Remove" buttons cannot be told apart by anyone
+listening to it.
+
+`formatCount` and `showCount` are exported from the framework-free `core`.

package/source/components/badge/core/count.ts

@@ -0,0 +1,37 @@
+/**
+ * The label a counter shows, and the one a screen reader hears.
+ *
+ * A badge is small, so a number that keeps growing has to stop somewhere —
+ * but "99+" read aloud as "ninety-nine plus" is a guess, not a count, which is
+ * why the two strings are computed together and the spoken one says what it
+ * means.
+ */
+export interface CountLabel {
+  /** What is printed in the badge. */
+  text: string;
+  /** What assistive technology reads instead, when the two differ. */
+  spoken?: string;
+}
+
+export function formatCount(
+  count: number,
+  max = 99,
+  format?: (value: number) => string,
+): CountLabel {
+  const show = (value: number) => (format ? format(value) : String(value));
+  if (!Number.isFinite(count)) return { text: "" };
+  const whole = Math.trunc(count);
+  if (whole <= max) return { text: show(whole) };
+  return { text: `${show(max)}+`, spoken: `more than ${show(max)}` };
+}
+
+/**
+ * Whether a counter should be on the page at all.
+ *
+ * Zero is the interesting case: a badge reading "0" is noise on a page and a
+ * spurious announcement in a screen reader, so it is left off unless the caller
+ * asks for it — but a caller sometimes does, when the number sits in a table of
+ * numbers and a gap would read as missing data.
+ */
+export const showCount = (count: number, showZero = false): boolean =>
+  Number.isFinite(count) && (count > 0 || (showZero && count === 0));

package/source/components/badge/core/index.ts

@@ -0,0 +1,2 @@
+export { formatCount, showCount, type CountLabel } from "./count";
+export type * from "./types";

package/source/components/badge/core/types.ts

@@ -0,0 +1,11 @@
+export type BadgeVariant = "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+
+/** `soft` is a tint, `solid` a filled block, `outline` a border only. */
+export type BadgeAppearance = "soft" | "solid" | "outline";
+
+export type BadgeSize = "sm" | "md";
+
+export interface BadgeLocaleText {
+  /** The remove button on a Tag. `label` is the tag's own text. */
+  remove(label: string): string;
+}

package/source/components/badge/index.ts

@@ -0,0 +1,7 @@
+export { Badge } from "./react/Badge";
+export type { BadgeProps } from "./react/Badge";
+export { Tag } from "./react/Tag";
+export type { TagProps } from "./react/Tag";
+export { defaultBadgeText } from "./react/locale";
+export type { BadgeSlot, TagSlot } from "./react/props";
+export * from "./core";

package/source/components/badge/passport.json

@@ -0,0 +1,332 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Badge",
+    "folder": "badge",
+    "exports": [
+      "Badge",
+      "Tag"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.1",
+    "files": [
+      "core/count.ts",
+      "core/index.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Badge.tsx",
+      "react/Tag.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:2f5c5c1d91e4edd8c8c6dc2a14ba66a140b738c9c7b889c7a0a54414513d3f2f"
+  },
+  "props": [
+    {
+      "name": "appearance",
+      "type": "enum",
+      "values": [
+        "outline",
+        "soft",
+        "solid"
+      ],
+      "typeText": "BadgeAppearance | undefined",
+      "required": false,
+      "default": "soft",
+      "origin": "derived",
+      "description": "Default `soft`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "aria-describedby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<BadgeSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "A number instead of children. Above `max` it reads \"99+\".",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "dot",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "A small filled circle before the label, for a status.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "formatValue",
+      "type": "function",
+      "signature": "((value: number) => string) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Format the number, e.g. with `Intl.NumberFormat`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Names the remove button when the tag's own text is not a plain string.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<BadgeLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 99,
+      "origin": "derived",
+      "description": "Where the count stops. Default 99.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onRemove",
+      "type": "function",
+      "signature": "(() => void) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Show a remove button. Without it a Tag is a Badge with a bit more padding.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLSpanElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "showZero",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Show a count of zero. Default false: an empty counter is noise.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "md",
+        "sm"
+      ],
+      "typeText": "BadgeSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "tabIndex",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "accent",
+        "danger",
+        "info",
+        "neutral",
+        "success",
+        "warning"
+      ],
+      "typeText": "BadgeVariant | undefined",
+      "required": false,
+      "default": "neutral",
+      "origin": "derived",
+      "description": "Default `neutral`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "HTMLAttributes<HTMLSpanElement>",
+      "omitted": [
+        "onRemove"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onRemove",
+      "signature": "(() => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "dot",
+    "icon",
+    "label",
+    "remove"
+  ],
+  "states": [
+    {
+      "attr": "data-appearance",
+      "values": [
+        "outline",
+        "soft",
+        "solid"
+      ]
+    },
+    {
+      "attr": "data-count"
+    },
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "accent",
+        "danger",
+        "info",
+        "neutral",
+        "success",
+        "warning"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 26,
+    "propsDescribed": 10,
+    "describedPct": 38,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}