@splenddev/kreativ-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,367 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Kreativ Core
+
+The design-system engine behind [Kreativ UI](https://github.com/Vincentvirtuoso/kreativ-ui).
+
+Define tokens, themes, and recipes. Core validates them and turns them into CSS variables and class names. It knows nothing about specific components or default looks; those live in Kreativ UI.
+
+> **Status:** early development. We're extracting this from Kreativ UI, so APIs and package boundaries may still change.
+
+**Using Kreativ UI?** You don't need to install this separately — `@splenddev/kreativ-ui` depends on it directly and stays version-matched automatically. Reach for this package on its own only if you're building your own design system or tooling on the same foundation, without Kreativ UI's components.
+
+## Install
+
+```bash
+npm install @splenddev/kreativ-core
+```
+
+## Quick start
+
+```tsx
+import {
+  defineTokens,
+  defineSemanticToken,
+  defineTheme,
+  ThemeProvider,
+} from "@splenddev/kreativ-core";
+
+const tokens = defineTokens({
+  colors: { blue: { 500: "#3b82f6", 400: "#60a5fa" } },
+});
+
+const semanticTokens = {
+  colors: {
+    brand: defineSemanticToken("{colors.blue.500}", "{colors.blue.400}"),
+  },
+};
+
+const theme = defineTheme({
+  tokens,
+  semanticTokens,
+  typography,
+  recipes,
+  sizes,
+  intensity: 50,
+});
+
+<ThemeProvider theme={theme}>
+  <App />
+</ThemeProvider>;
+```
+
+Light and dark values resolve automatically, and every token becomes a CSS variable like `--kui-brand`.
+
+Building on Kreativ UI? Use its `KreativUIProvider` instead (see [Providers](#providers)).
+
+## Core vs Kreativ UI
+
+Core is the machinery. Kreativ UI is the product: the components plus the default tokens, sizes, typography, and recipes that give it its look.
+
+```
+Kreativ Core   tokens · semantic tokens · typography · sizes · recipes
+               themes · validation · CSS variables · component metadata · React runtime
+      │
+      ▼
+Kreativ UI     components + the default design language
+      │
+      ▼
+Your app
+```
+
+Use Kreativ UI to build apps. Reach for Core when you're building your own design system or tooling on the same foundation. Defaults (tokens, sizes, typography, recipes) belong to Kreativ UI, never to Core.
+
+### Providers
+
+The provider is split the same way:
+
+- **`ThemeProvider`** (Core) is UI-agnostic. It handles theme composition, color mode, token resolution, CSS variables, and the theme context. It knows nothing about specific components.
+- **`KreativUIProvider`** (Kreativ UI) is a thin wrapper around `ThemeProvider`. It adds the default theme, the overlay root used by popovers, dialogs, and toasts, and typed per-component `defaults`. Those depend on Kreativ UI's own components, so they can't live in Core.
+
+## Concepts
+
+### Tokens
+
+Tokens are the raw values of a design system. They're mode-independent and terminal, so a primitive token can't reference another token.
+
+```ts
+const tokens = defineTokens({
+  colors: { blue: { 500: "#3b82f6", 600: "#2563eb" } },
+  spacing: { sm: "0.5rem", md: "1rem" },
+});
+```
+
+Built-in groups: `colors`, `spacing`, `radii`, `fonts`, `fontSizes`, `fontWeights`, `lineHeights`, `letterSpacing`, `shadows`, `animations`, and `breakpoints`. Custom groups work too.
+
+### Semantic tokens
+
+Semantic tokens describe meaning instead of raw values. Components consume `{colors.brand}` rather than `{colors.blue.500}`, so you can re-theme without touching a component.
+
+```ts
+defineSemanticToken("{colors.blue.500}", "{colors.blue.400}"); // light, dark
+defineSemanticToken("{colors.white}"); // same in both modes
+```
+
+They can reference primitives or other semantic tokens. Keeping all references on the semantic side keeps the token graph predictable and makes cycle detection simple.
+
+### Typography
+
+Typography presets are defined separately from font tokens and reference them:
+
+```ts
+const typography = defineTypography({
+  body: {
+    fontFamily: "{fonts.body}",
+    fontSize: "{fontSizes.md}",
+    fontWeight: "{fontWeights.normal}",
+    lineHeight: "{lineHeights.normal}",
+  },
+  heading: {
+    fontFamily: "{fonts.heading}",
+    fontSize: "{fontSizes.2xl}",
+    fontWeight: "{fontWeights.bold}",
+  },
+});
+```
+
+`resolveTypography()` turns a preset into CSS properties at runtime.
+
+### Sizes
+
+Size scales give components consistent dimensions:
+
+```ts
+const sizes = defineSizes({
+  sm: {
+    height: "2rem",
+    paddingX: "0.75rem",
+    fontSize: "{typography.body}",
+    gap: "0.375rem",
+    iconSize: "0.875rem",
+    radius: "0.8rem",
+  },
+  md: {
+    height: "2.5rem",
+    paddingX: "1rem",
+    fontSize: "{typography.body}",
+    gap: "0.5rem",
+    iconSize: "1rem",
+    radius: "1rem",
+  },
+});
+```
+
+A size can define `height`, `width`, `paddingX`, `paddingY`, `fontSize`, `gap`, `iconSize`, `radius`, and `separatorSize`. Its `fontSize` is tied to the typography system and must reference a typography preset.
+
+### Recipes
+
+A recipe is a component's styling contract: base styles, variants, default variants, and compound variants.
+
+```ts
+const buttonRecipe = defineRecipe({
+  base: "inline-flex items-center justify-center",
+  variants: {
+    variant: { solid: "...", outline: "...", ghost: "..." },
+    color: { brand: "...", destructive: "..." },
+  },
+  defaultVariants: { variant: "solid", color: "brand" },
+  compoundVariants: [
+    { conditions: { variant: "solid", color: "brand" }, className: "..." },
+  ],
+});
+
+resolveRecipe(buttonRecipe, props);
+```
+
+`resolveRecipe` applies default variants, resolves matching variants, resolves matching compound variants (exact prop matching), then combines the class names.
+
+### Themes
+
+A theme brings every layer together, plus lightweight metadata that tools like the Kreativ CLI and Playground can read.
+
+```ts
+const theme = defineTheme({
+  tokens,
+  semanticTokens,
+  typography,
+  recipes,
+  sizes,
+  intensity: 50,
+  metadata: {
+    name: "My Theme",
+    description: "A custom Kreativ theme",
+    author: "Author",
+  },
+});
+```
+
+`defineTheme()` keeps the exact shape you pass in while validating the relationships between layers. Metadata fields are `name`, `description`, `author`, and `source`, all optional.
+
+#### Overriding and extending
+
+Customize an existing theme with a `ThemeOverride`:
+
+```ts
+const override = {
+  tokens: { colors: { blue: { 500: "#7c3aed" } } },
+  semanticTokens: {
+    colors: { brand: defineSemanticToken("{colors.blue.500}") },
+  },
+  intensity: 60,
+};
+```
+
+Or extend one layer at a time with `extendTokens()`, `extendSemanticTokens()`, `extendTypography()`, `extendSizes()`, and `extendRecipes()`.
+
+### Validation
+
+`defineTheme()` checks your theme as you write it:
+
+- Token references must resolve to existing paths. `{colors.blue.500}` has to actually exist.
+- Primitive tokens can't contain references. Semantic tokens are the reference layer.
+- Typography fields may reference primitive tokens, and those paths must exist.
+- A size's `fontSize` must reference a typography preset, not a raw CSS value.
+- Semantic cycles (`brand → accent → brand`) are invalid. These are caught at runtime.
+
+## Runtime
+
+### Resolving tokens and CSS variables
+
+```ts
+const resolved = resolveTokens(theme.tokens, theme.semanticTokens, "light");
+// Record<string, string>
+
+const cssVars = tokensToCssVars(resolved, "light", theme.intensity);
+```
+
+Semantic values resolve for the active color mode. Primitive tokens are named by path, semantic colors by their semantic name, and the runtime also exposes the current mode and intensity:
+
+```
+colors.blue.500  →  --kui-colors-blue-500
+colors.brand     →  --kui-brand
+                    --kui-mode
+                    --kui-intensity
+```
+
+Color values are normalized to RGB channels where appropriate, so the variables work with modern color-manipulation patterns.
+
+### ThemeProvider
+
+`ThemeProvider` sets up the theme for a React tree. It handles theme composition, color-mode state, system color preference, token resolution, CSS variable generation, a fallback component size, and optional theme transitions.
+
+Color mode can be `"light"`, `"dark"`, or `"system"` (which follows `prefers-color-scheme`).
+
+The theme context exposes:
+
+```ts
+{
+  (theme, mode, resolvedMode, setMode, fallbackSize, tokens);
+}
+```
+
+so components can use the active theme without being coupled to any default theme.
+
+### createComponent and metadata
+
+`createComponent()` builds a ref-forwarding component and attaches Kreativ metadata through `__kui`:
+
+```tsx
+const Component = createComponent<Props, HTMLElement>({
+  displayName: "Component",
+  __kui: { role: "display" },
+  render(props, ref) {
+    return <div ref={ref} />;
+  },
+});
+```
+
+Metadata gives tooling, generators, and composition systems a machine-readable description of a component:
+
+```ts
+interface KuiMeta {
+  role?:
+    | "action"
+    | "formControl"
+    | "overlay"
+    | "layout"
+    | "display"
+    | "disclosure"
+    | "navigation"
+    | string;
+  groupSlot?: string; // logical compound group, e.g. "Tooltip"
+  formControl?: "single" | "compound";
+  supports?: {
+    disabled?: boolean;
+    invalid?: boolean;
+    required?: boolean;
+    [key: string]: boolean | undefined;
+  };
+  skeleton?: KuiSkeletonHint;
+}
+```
+
+Use `hasKuiMeta(value)` to detect metadata at runtime.
+
+**Compound components.** Parts like `Tooltip.Trigger`, `Tooltip.Content`, and `Tooltip.Arrow` carry metadata (e.g. `groupSlot: "Tooltip"`) so tools can see they belong together. The root doesn't need `createComponent()`. A root that only owns state and context renders no DOM, so it has no ref or metadata to forward.
+
+### Prop composition
+
+`createFromProps()` merges props deterministically. Later layers win:
+
+```
+providerDefaults → defaultProps → generatedProps → consumerProps
+```
+
+```ts
+createFromProps({
+  providerDefaults,
+  defaultProps,
+  generatedProps,
+  consumerProps,
+});
+```
+
+- **`className`**: concatenated in priority order.
+- **`style`**: shallow merged.
+- **Event handlers** (anything matching `on[A-Z]`): composed, not overwritten, running from lowest to highest priority.
+- **Refs**: not handled here. Use `composeRefs(...)`.
+
+### Controllable state
+
+`useControllableState()` is the standard controlled/uncontrolled pattern:
+
+```ts
+const [value, setValue] = useControllableState({
+  value,
+  defaultValue,
+  onChange,
+});
+```
+
+A component is controlled when `value` is defined. In controlled mode, `setValue()` only calls `onChange()`. In uncontrolled mode it also updates internal state. Updates are skipped when the next value is `Object.is`-equal to the current one.
+
+### Responsive styles
+
+Responsive styles are generated from the active theme's breakpoint tokens, so components never hard-code breakpoints. The generated rules come back together with a data attribute that scopes them to the element.
+
+## Design principles
+
+- **Tokens before components.** Components consume the design system; they don't invent their own visual language.
+- **Meaning over raw values.** Prefer `{colors.brand}` to `{colors.blue.500}` when the value is a role.
+- **Strict primitives, flexible semantics.** Primitives stay terminal; semantic tokens do the referencing.
+- **Metadata is part of the contract.** A component's role, relationships, and supported states are described to tooling, not just rendered.
+- **Predictable composition.** Prop merging, theme extension, recipe resolution, and token resolution all follow explicit precedence.
+- **Defaults belong to the implementation.** Core defines the system; Kreativ UI defines the look.
+
+## Contributing
+
+While we finish extracting Core from Kreativ UI, please prefer:
+
+- small, composable primitives
+- explicit types
+- predictable merge behavior
+- compile-time validation where possible, runtime validation where necessary
+- framework-specific behavior kept at the runtime boundary
+- no dependency on Kreativ UI defaults
+
+## License
+
+See the repository license.