@krizaka/sovkora-design-system 0.0.0-stage → 4.0.0

package/src/icon.tsx

@@ -0,0 +1,74 @@
+/**
+ * @file icon.tsx
+ * @description Centralized polymorphic icon registry for the Sovkora UI.
+ *
+ * Single ICON_REGISTRY dictionary housing custom-crafted, minimalist geometric
+ * SVG paths. Every path uses vector-effect="non-scaling-stroke" for visual
+ * thickness consistency during layout motion sweeps.
+ *
+ * Usage: <Icon name="dashboard" size={20} className="text-accent" />
+ *
+ * Default: 24×24 viewBox, 1.25px stroke, round caps, currentColor.
+ */
+
+import React from "react";
+
+import type { IconName } from "./icon.registry";
+import { ICON_REGISTRY } from "./icon.registry";
+
+export type { IconName };
+
+interface IconProps {
+  /** Icon identifier from the registry */
+  name: IconName;
+  /** Pixel size (width & height). Defaults to 20. */
+  size?: number;
+  /** Additional CSS classes */
+  className?: string;
+  /** Accessible label — if omitted, icon is decorative (aria-hidden) */
+  label?: string;
+  /** Drawn when `name` is not in the registry (a key that comes from data, e.g. a Studio's `iconKey`). */
+  fallback?: IconName;
+}
+
+/**
+ * Polymorphic SVG icon wrapper with uniform fallback configuration.
+ *
+ * - Default fine strokeWidth: 1.25
+ * - Round caps and joins
+ * - Size control via `size` prop
+ * - vector-effect="non-scaling-stroke" on all paths
+ *
+ * @param props — Icon configuration
+ * @returns SVG element with the requested icon path
+ */
+export function Icon({ name, size = 20, className = "", label, fallback }: Readonly<IconProps>) {
+  const paths = ICON_REGISTRY[name] ?? (fallback ? ICON_REGISTRY[fallback] : undefined);
+  if (!paths) return null;
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.25"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      role={label ? "img" : "presentation"}
+      aria-label={label}
+      aria-hidden={!label}
+    >
+      {paths}
+    </svg>
+  );
+}
+
+/* ═══════════════════════════════════════════════════════════
+   ICON_REGISTRY — Minimalist Geometric SVG Paths
+   ─────────────────────────────────────────────────────────
+   Every path entry features vector-effect="non-scaling-stroke"
+   for visual thickness consistency during layout motion sweeps.
+   ═══════════════════════════════════════════════════════════ */

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @file index.ts
+ * @description Public surface of `@krizaka/sovkora-design-system` — the Sovkora identity on the Krizaka platform:
+ * the theme (`./theme.css`, --kz-* overrides; import it once at the app root, after `tailwindcss`), the product
+ * composites, and a few @krizaka/ui primitives re-exported with their Sovkora defaults (Button's `primary`). Every
+ * other primitive — Card, Dialog, Toaster, Loader, Stepper, Meter, NumberTicker… — is imported from @krizaka/ui.
+ */
+
+// ── Design tokens (framework-agnostic, from sovkora-shared) ─────────────────
+// The token values for React Native and the CLI (the Sovkora orange of @krizaka/tokens/native). The web theme is
+// theme.css (--kz-* roles).
+export type { ThemeColors, ThemeName, Tokens } from "@krizaka/sovkora-shared";
+export { radius, shadows, status, themes, tokens, typeScale } from "@krizaka/sovkora-shared";
+
+// ── Class helpers ───────────────────────────────────────────────────────────
+export { cn } from "@krizaka/ui/cn";
+
+// ── Icon registry ───────────────────────────────────────────────────────────
+export type { IconName } from "./icon";
+export { Icon } from "./icon";
+
+// ── Primitives from @krizaka/ui (re-exported) ───────────────────────────────
+export type { BadgeProps, BadgeVariant, BadgeVariants } from "./components/Badge";
+export { Badge, badgeVariants } from "./components/Badge";
+export type { ButtonProps, ButtonVariants, IconButtonProps } from "./components/Button";
+export { Button, buttonVariants, IconButton } from "./components/Button";
+export type { InputProps } from "./components/Input";
+export { Field, Input, Select, Textarea } from "./components/Input";
+export type { SkeletonGroupProps, SkeletonProps } from "./components/Skeleton";
+export { Skeleton, SkeletonGroup, skeletonVariants } from "./components/Skeleton";
+
+// ── Sovkora composites ──────────────────────────────────────────────────────
+export type { ChatShowcaseLabels, ChatShowcaseProps } from "./components/ChatShowcase";
+export { ChatShowcase } from "./components/ChatShowcase";
+export type { ClipPlayerLabels, ClipPlayerProps, ClipSources } from "./components/ClipPlayer";
+export { ClipPlayer } from "./components/ClipPlayer";
+export type { CommandPaletteItem, CommandPaletteLabels, CommandPaletteProps } from "./components/CommandPalette";
+export { CommandPalette } from "./components/CommandPalette";
+export type { RunFact, RunFactsProps } from "./components/RunFacts";
+export { RunFacts } from "./components/RunFacts";
+export { SentinelMini } from "./components/SentinelMini";
+export type { VideoResultFact, VideoResultLabels, VideoResultProps } from "./components/VideoResult";
+export { VideoResult } from "./components/VideoResult";

package/src/meta.ts

@@ -0,0 +1,76 @@
+// The documentation of a component of the kit, carried by its code — the same format as @krizaka/ui's (`src/meta.ts`
+// in krizaka-ui), plus what a product component owes its reader: why it exists above Krizaka UI, the primitives it is
+// built on, and, when it is deprecated, what replaces it. Each component has a `<name>.meta.ts` beside it; never built
+// into the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as
+// /docs/sovkora/ui/<name>, and `scripts/registry.test.mjs` fails when an exported component has none.
+
+/** Every documented component of the kit. */
+export type ComponentName =
+  | "badge"
+  | "button"
+  | "chat-showcase"
+  | "clip-player"
+  | "command-palette"
+  | "icon"
+  | "run-facts"
+  | "sentinel-mini"
+  | "skeleton"
+  | "video-result";
+
+/** A component of @krizaka/ui, documented at krizaka.com/docs/ui/<name>: `ui/badge`, `ui/button`. */
+export type UiComponent = `ui/${string}`;
+
+/** A component a reader should know about: one of this kit, or one of @krizaka/ui. */
+export type Reference = ComponentName | UiComponent;
+
+/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: see `deprecated`. */
+export type Status = "stable" | "beta" | "deprecated";
+
+/** The group of the catalogue (the @krizaka/ui categories). */
+export type Category =
+  "actions" | "forms" | "navigation" | "overlays" | "feedback" | "data-display" | "layout" | "foundations";
+
+/** A named example: `registry/examples/<component>/<name>.tsx` — at most 40 lines, a realistic product scenario. */
+export interface Example {
+  /** The file name, kebab-case (`sovereign-answer`). */
+  readonly name: string;
+  /** A short title (`A sovereign answer`). */
+  readonly title: string;
+  /** One or two sentences: the situation it shows. */
+  readonly description: string;
+}
+
+export interface KeyboardInteraction {
+  readonly keys: string;
+  readonly action: string;
+}
+
+export interface ComponentMeta {
+  /** The display name: `Chat showcase`. */
+  readonly title: string;
+  /** One sentence: what it is. */
+  readonly summary: string;
+  /** Why it exists above Krizaka UI: what the primitive alone does not say about Sovkora. */
+  readonly why: string;
+  readonly status: Status;
+  /** Required when `status` is `deprecated`: since when, what replaces it, when it goes. */
+  readonly deprecated?: { readonly since: string; readonly use: Reference; readonly removedIn: string };
+  readonly category: Category;
+  /** The kit's components are web components; the mobile app takes the tokens (`@krizaka/sovkora-shared`). */
+  readonly platforms: "web";
+  /** The @krizaka/ui components it is built on (`ui/command`): a product component composes, it never copies. */
+  readonly builtOn: readonly UiComponent[];
+  readonly whenToUse: readonly string[];
+  readonly whenNotToUse: readonly { readonly when: string; readonly use?: Reference }[];
+  readonly bestPractices: readonly string[];
+  readonly accessibility: { readonly keyboard: readonly KeyboardInteraction[]; readonly notes: readonly string[] };
+  readonly related: readonly Reference[];
+  readonly web: {
+    /** The names to import. */
+    readonly imports: readonly string[];
+    /** The entry they come from: `.` (the package root, the only one). */
+    readonly entry?: ".";
+    /** The examples, in reading order; the first one is the preview. Empty only for a deprecated component. */
+    readonly examples: readonly Example[];
+  };
+}