panelize 0.0.0-stage → 0.1.0

package/docs/shell.md

@@ -0,0 +1,57 @@
+# Shell (`Panels` / `Panel`)
+
+`Panels` is the outer shell of a view. Setting it up well matters more than any control.
+
+Default `Panels` is an **absolute** column (`inset` when `fill`). `relative` opt-in. `horizontal` is a row (sidebar + main). Overlay shells belong on `Panels`, not `Rows fill`.
+
+Direct children: only `Panel`. **One `Panel` is allowed.** Nested shells: a `Panel` may contain another `Panels`.
+
+`Panel` is a section (surface). `variant` is `muted` / `base` / `highlighted` (default `base`). It publishes `--panelize-bg`, `--panelize-text`, `--panelize-text-muted`, `--panelize-text-highlighted`, `--panelize-border`. Nested panels and children share those. `dark` / `light` are schemes on the provider, not panel variants.
+
+## Host height
+
+A filled shell needs a viewport-tall host:
+
+```css
+html,
+body,
+#root {
+  height: 100%;
+}
+```
+
+The library does not set `html` / `body`. For a long in-flow document, drop host `height` and use `min-height: 100%`.
+
+## Page (scroll the shell)
+
+Default column — do not add `horizontal`. Do not put `fill` on the inner `Panel` (that locks height). Use `minHeight='100%'` so a short window still paints. Do not center on the scrolling `Panels`; center on inner `Rows`.
+
+```tsx
+<Panels fill scroll='vertical'>
+  <Panel variant='muted' minHeight='100%' padding='base'>
+    <Heading level={1}>Title</Heading>
+    <Text muted>Long page copy…</Text>
+  </Panel>
+</Panels>
+```
+
+## Split (scroll the pane)
+
+`horizontal` + `fill` on `Panels`. `scroll` on the pane `Panel`, not the outer shell. Sidebar: `width`. Main: `flex` (not `fill` — `fill` fights the sidebar). `stack` on this row: **at most** this wide → column (not Tailwind `md:` and-up).
+
+```tsx
+<Panels horizontal fill stack='sm'>
+  <Panel variant='muted' width='12rem'>
+    <Text>Nav</Text>
+  </Panel>
+  <Panel variant='base' flex scroll='vertical'>
+    <Text>Main</Text>
+  </Panel>
+</Panels>
+```
+
+## `scroll`
+
+Only on `Panels` and `Panel`. `vertical` clips x. `horizontal` / `both` need a child actually wider than the box (`width` / `minWidth` on children). Nested `scroll` in a split needs `flex` on the pane (`min-width` / `min-height` 0) so it can shrink.
+
+`Panel` / `Row` / `Col` / `Div` are `flex-shrink: 0` until `flex`.

package/docs/text.md

@@ -0,0 +1,26 @@
+# Text
+
+Visible copy must use a type primitive so it inherits the nearest `Panel` (`--panelize-text`, muted, highlighted) and theme type tokens.
+
+| Component  | Element   | Notes                                                                                                                         |
+| ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Text`     | `p`       | Body. Omit color → panel `text.base`.                                                                                         |
+| `Heading`  | `h1`–`h6` | Required `level` `1`–`6`. Omit `size` → theme heading size for that level. Omit `weight` → `bold`. Omit `family` → `display`. |
+| `Span`     | `span`    | Nested in `Text` / `Span`: omit size/weight/`family` → inherit. Omit color → CSS `inherit`.                                   |
+| `TextLink` | `a`       | Default chroma `primary`. Nested omit size/weight/`family` → inherit.                                                         |
+| `Label`    | `label`   | Caption for controls. Prefer `label` prop; `htmlFor` + control `id`. Wrap `Switch` / `Checkbox` / `Radio`.                    |
+
+None of these is a layout shell: no `fill` / `flex` / padding. Gap belongs on `Rows` / `Cols` / `Grid` / `Div`.
+
+`muted` / `highlighted` use the panel `text` object. `color='primary'` / `secondary` / `accent` → `brand.*.base`. `color='danger'` / `warning` / `success` / `info` → `status.*.base`. Raw CSS `color` wins. If both flags, `highlighted` wins.
+
+Size: `fontSizes` tokens or CSS. Weight: omit on `Text` = `base` (400). Family: `base` / `display` / `mono`. The library does not load font files.
+
+```tsx
+<Heading level={1} uppercase color='primary'>
+  Panelize
+</Heading>
+<Text muted size='small'>
+  Nested <Span weight='bold'>bold</Span> and <TextLink href='/docs'>Docs</TextLink>
+</Text>
+```

package/docs/theme.md

@@ -0,0 +1,121 @@
+# Theme and hooks
+
+Appearance comes from the theme, not one-off color props on every box. That is how views stay standardized.
+
+## `createPanelizeTheme`
+
+Author schemes, surfaces, brand, type, and component defaults. Export a **stable** object. Omit any key to keep the library default. Full keys: [examples/panelize.theme.md](../examples/panelize.theme.md). Frozen gray bank: `palette` from `'panelize'` (not a theme key).
+
+```ts
+import { createPanelizeTheme, palette } from 'panelize'
+
+export const panelizeTheme = createPanelizeTheme({
+  colors: {
+    dark: {
+      app: { background: palette.gray.extraDark, text: palette.gray.extraLight },
+      muted: {
+        background: palette.gray.dark,
+        text: { base: palette.white, muted: palette.gray.base, highlighted: palette.white },
+      },
+    },
+  },
+  brand: { primary: '#ff9f2e' },
+})
+```
+
+`colors: { dark, light }` are schemes. After create, **`theme.colors` is the active slice** (`muted` / `base` / `highlighted` / `app`) — not `{ dark, light }`. Both maps are `theme.colorSchemes`. Surfaces belong under a scheme (`colors.dark.muted`). A top-level `colors.muted` is ignored. `dark` is a scheme, not a panel variant.
+
+Brand (`primary` / `secondary` / `accent`) and status (`danger` / `warning` / `success` / `info`) are global, shared across schemes. Library `secondary` / `accent` follow `primary` until set. Status does not follow `primary`. Hosts set their brand kit here; the library defaults stay neutral.
+
+## `PanelizeProvider`
+
+Puts that object on the tree and wraps a canvas (`color-scheme` from `mode`; optional `app` paint). `mode` (`dark` default) selects the slice. Hosts own the toggle — there is no library toggle. `prefers-color-scheme` is host-side.
+
+Do **not** take over the host’s styled-components `ThemeProvider`. Do **not** set `html` / `body`.
+
+Without a provider, components still render using `defaultTheme` (`mode` `dark`). Always wrap a real host.
+
+```tsx
+<PanelizeProvider theme={panelizeTheme} mode={mode}>
+  {children}
+</PanelizeProvider>
+```
+
+## `usePanelizeTheme`
+
+**Use this in views and custom components** that need colors, space, or type from the kit. `.colors` is the current scheme’s surfaces. `.mode` is `'dark'` | `'light'`. `.brand` / `.status` are the shared slots. `.space` / `.fontSizes` / … are the scales.
+
+Do not invent a parallel palette in a custom component. Read the theme (or inherit `--panelize-*` from the nearest `Panel`). Nested `Panel` `variant` changes the CSS variables for descendants.
+
+```tsx
+function Stat({ label, value }: { label: string; value: string }) {
+  const { colors } = usePanelizeTheme()
+  return (
+    <Div padding='small' borderWidth='extraSmall' borderColor={colors.base.border}>
+      <Text muted size='small'>
+        {label}
+      </Text>
+      <Text highlighted>{value}</Text>
+    </Div>
+  )
+}
+```
+
+Place `Stat` in a `Col` / `Row` / `Cell` / `Panel`. `Stat` does not take `alignX`.
+
+## Recipes
+
+Author the theme once in the host, export a stable object, and pass `mode` from wherever the host keeps its color-scheme state. The library has no toggle and does not read `prefers-color-scheme`.
+
+**Brand kit.** `secondary` and `accent` follow `primary` until set. Status colors do not follow brand.
+
+```ts
+export const panelizeTheme = createPanelizeTheme({
+  brand: {
+    primary: '#6d5dfc',
+    secondary: '#00b8a9',
+    accent: { base: '#f9c80e', hover: '#ffd84d' },
+  },
+  status: { danger: '#d64550' },
+})
+```
+
+**Both schemes.** Author `dark` and `light` surfaces together. Omit any surface to keep the default.
+
+```ts
+createPanelizeTheme({
+  colors: {
+    dark: { app: { background: '#0e0e10', text: '#ececec' } },
+    light: {
+      app: { background: '#ffffff', text: '#1a1a1a' },
+      muted: {
+        background: '#f3f3f5',
+        text: { base: '#1a1a1a', muted: '#6b6b73', highlighted: '#000000' },
+      },
+    },
+  },
+})
+```
+
+**Fonts and type scale.** The library does not load font files. Point the tokens at what the host loads.
+
+```ts
+createPanelizeTheme({
+  fontFamilies: { base: 'Inter, sans-serif', display: '"Fraunces", serif' },
+  fontSizes: { base: '1.0625rem' },
+})
+```
+
+**Component defaults.** Change a control everywhere instead of on every instance. `defaults.textarea` and `defaults.select` start from the merged `defaults.input`.
+
+```ts
+createPanelizeTheme({
+  defaults: {
+    button: { borderRadius: 'small', paddingX: 'large' },
+    input: { borderRadius: 'small' },
+    select: { listMaxHeight: '12rem' },
+  },
+})
+```
+
+**Custom component on the theme.** Read `usePanelizeTheme` or inherit `--panelize-*` from the nearest `Panel`; do not hard-code hexes. See `Stat` above.

package/examples/AGENTS.md

@@ -0,0 +1,9 @@
+# Agent notes (UI)
+
+This app builds views with [Panelize](https://github.com/jayzizzle/panelize).
+
+- Before writing JSX, read `node_modules/panelize/llms.txt` and `node_modules/panelize/docs/composition.md`. Copyable trees: `node_modules/panelize/docs/recipes.md`.
+- Import from `'panelize'`. Wrap the app once with `PanelizeProvider`.
+- Host CSS owns `html` / `body` / `#root` height. The library does not set them.
+- Follow the pairing rules: `Panels` > `Panel`; `Rows` > `Row`; `Cols` > `Col`; `Grid` > `Cell`. Two or more per track.
+- The wrapper places things. Controls and type do not take `alignX` / `flex` / padding to position themselves.

package/examples/cursor-rule.mdc

@@ -0,0 +1,17 @@
+---
+description: Compose views with Panelize layout primitives and type
+alwaysApply: true
+---
+
+# Panelize (this app)
+
+Before writing or changing UI, read `node_modules/panelize/llms.txt` and `node_modules/panelize/docs/composition.md`.
+
+- Import from `'panelize'`. Wrap the tree with `PanelizeProvider`.
+- `Panels` is the view shell. Direct children are only `Panel` (one is allowed).
+- `Row` only under `Rows` (two or more). `Col` only under `Cols` (two or more). `Cell` only under `Grid` (two or more).
+- One band of content → `Panel` or `Div`, not a track of one item.
+- The wrapper owns place (`alignX` / `alignY`, `flex`, `fill`, `gap`). Controls do not position themselves.
+- Visible copy uses `Text` / `Heading` / `Span` / `TextLink` / `Label`.
+- Custom components use `usePanelizeTheme` (or inherit `--panelize-*` from the nearest `Panel`). Do not invent a parallel palette.
+- Forms, buttons, and chips are bonus. Core is panels, tracks, grid, and text.

package/examples/panelize.theme.md

@@ -0,0 +1,312 @@
+# Theme keys
+
+Every key `createPanelizeTheme` accepts. Omit any key to keep the library default.
+
+```ts
+import { createPanelizeTheme, palette } from 'panelize'
+
+export const panelizeTheme = createPanelizeTheme({
+  colors: {
+    dark: {
+      app: {
+        background: '#121212',
+        text: '#e8e8e8',
+      },
+      muted: {
+        background: '#222222',
+        text: {
+          base: palette.gray.extraLight,
+          muted: palette.gray.base,
+          highlighted: palette.white,
+        },
+        border: palette.gray.dark,
+      },
+      base: {
+        background: '#333333',
+        text: {
+          base: palette.gray.extraLight,
+          muted: palette.gray.light,
+          highlighted: palette.white,
+        },
+        border: palette.gray.base,
+      },
+      highlighted: {
+        background: palette.gray.dark,
+        text: {
+          base: palette.white,
+          muted: palette.gray.light,
+          highlighted: palette.white,
+        },
+        border: palette.gray.base,
+      },
+    },
+    light: {
+      app: {
+        background: '#fafafa',
+        text: '#121212',
+      },
+      muted: {
+        background: '#f2f2f2',
+        text: {
+          base: '#222222',
+          muted: palette.gray.base,
+          highlighted: palette.black,
+        },
+        border: palette.gray.light,
+      },
+      base: {
+        background: '#f7f7f7',
+        text: {
+          base: '#333333',
+          muted: palette.gray.base,
+          highlighted: palette.black,
+        },
+        border: palette.gray.base,
+      },
+      highlighted: {
+        background: palette.white,
+        text: {
+          base: palette.gray.dark,
+          muted: palette.gray.base,
+          highlighted: palette.black,
+        },
+        border: palette.gray.base,
+      },
+    },
+  },
+  brand: {
+    primary: {
+      base: '#ff9f2e',
+      hover: '#ffb762',
+      active: '#f1962b',
+    },
+    secondary: {
+      base: '#ff9f2e',
+      hover: '#ffb762',
+      active: '#f1962b',
+    },
+    accent: {
+      base: '#ff9f2e',
+      hover: '#ffb762',
+      active: '#f1962b',
+    },
+  },
+  status: {
+    danger: '#f2555a',
+    warning: '#ffd60a',
+    success: '#4ade80',
+    info: '#38bdf8',
+  },
+  space: {
+    none: '0rem',
+    extraSmall: '0.25rem',
+    small: '0.5rem',
+    base: '1rem',
+    large: '1.5rem',
+    extraLarge: '2rem',
+  },
+  borderWidths: {
+    none: '0',
+    extraSmall: '1px',
+    small: '2px',
+    base: '4px',
+    large: '8px',
+    extraLarge: '12px',
+  },
+  breakpoints: {
+    sm: '40rem',
+    md: '48rem',
+    lg: '64rem',
+  },
+  fontSizes: {
+    extraSmall: '0.75rem',
+    small: '0.875rem',
+    base: '1rem',
+    large: '1.25rem',
+    extraLarge: '1.5rem',
+  },
+  fontWeights: {
+    thin: '100',
+    base: '400',
+    bold: '700',
+    heavy: '800',
+  },
+  fontFamilies: {
+    base: '"Open Sans", sans-serif',
+    display: 'Montserrat, sans-serif',
+    mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+  },
+  // Unitless. `Text` leading. Switch track height is type × this. Checkbox / Radio use `1em`.
+  lineHeight: 1.2,
+  radii: {
+    none: '0',
+    extraSmall: '0.125rem',
+    small: '0.25rem',
+    base: '0.5rem',
+    large: '0.75rem',
+    extraLarge: '1rem',
+  },
+  defaults: {
+    panel: {
+      padding: 'none',
+      margin: 'none',
+      borderWidth: 'none',
+      borderRadius: 'none',
+    },
+    panels: {
+      padding: 'none',
+      margin: 'none',
+      gap: 'none',
+    },
+    // No panels.alignX / alignY: Panels is a column, or `horizontal` / `stack`.
+    rows: {
+      padding: 'none',
+      margin: 'none',
+      gap: 'none',
+      alignX: 'stretch',
+      alignY: 'start',
+    },
+    row: {
+      padding: 'none',
+      margin: 'none',
+      height: 'auto',
+      borderWidth: 'none',
+      borderRadius: 'none',
+    },
+    cols: {
+      padding: 'none',
+      margin: 'none',
+      gap: 'none',
+      alignX: 'start',
+      alignY: 'stretch',
+    },
+    col: {
+      padding: 'none',
+      margin: 'none',
+      width: 'auto',
+      borderWidth: 'none',
+      borderRadius: 'none',
+    },
+    grid: {
+      padding: 'none',
+      margin: 'none',
+      gap: 'none',
+      alignX: 'stretch',
+      alignY: 'stretch',
+    },
+    cell: {
+      padding: 'none',
+      margin: 'none',
+      borderWidth: 'none',
+      borderRadius: 'none',
+    },
+    div: {
+      padding: 'none',
+      margin: 'none',
+      borderWidth: 'none',
+      borderRadius: 'none',
+    },
+    text: {
+      size: 'base',
+      weight: 'base',
+    },
+    heading: {
+      size: {
+        1: '2rem',
+        2: '1.5rem',
+        3: '1.17rem',
+        4: '1rem',
+        5: '0.83rem',
+        6: '0.67rem',
+      },
+      weight: 'bold',
+      family: 'display',
+    },
+    textLink: {
+      color: 'primary',
+      hover: 'primary',
+      hoverUnderline: false,
+    },
+    button: {
+      color: 'primary',
+      size: 'small',
+      weight: 'bold',
+      ink: palette.black,
+      hover: { color: palette.black },
+      paddingX: 'base',
+      paddingY: 'small',
+      gap: 'extraSmall',
+      borderWidth: 'extraSmall',
+      borderRadius: 'base',
+    },
+    chip: {
+      color: 'primary',
+      size: 'extraSmall',
+      weight: 'bold',
+      tint: '12%',
+      paddingX: 'base',
+      paddingY: 'extraSmall',
+      gap: 'extraSmall',
+      borderRadius: '999px',
+      uppercase: true,
+    },
+    input: {
+      color: 'primary',
+      size: 'small',
+      weight: 'base',
+      paddingX: 'base',
+      paddingY: 'small',
+      borderWidth: 'extraSmall',
+      borderRadius: 'base',
+    },
+    textarea: {
+      color: 'primary',
+      size: 'small',
+      weight: 'base',
+      paddingX: 'base',
+      paddingY: 'small',
+      borderWidth: 'extraSmall',
+      borderRadius: 'base',
+      resize: false,
+      rows: 3,
+    },
+    select: {
+      color: 'primary',
+      size: 'small',
+      weight: 'base',
+      paddingX: 'base',
+      paddingY: 'small',
+      borderWidth: 'extraSmall',
+      borderRadius: 'base',
+      listMaxHeight: '16rem',
+      listOffset: 'extraSmall',
+      optionPaddingX: 'base',
+      optionPaddingY: 'extraSmall',
+      listZIndex: 1100,
+      listShadow: '0 8px 24px rgb(0 0 0 / 35%)',
+    },
+    switch: {
+      color: 'primary',
+      size: 'base',
+      ink: palette.white,
+      widthFactor: 2,
+      insetFactor: 0.2,
+      borderRadius: '999px',
+    },
+    checkbox: {
+      color: 'primary',
+      size: 'base',
+      ink: palette.black,
+      borderWidth: 'extraSmall',
+      borderRadius: 'small',
+    },
+    radio: {
+      color: 'primary',
+      size: 'base',
+      borderWidth: 'extraSmall',
+      borderRadius: '999px',
+      insetFactor: 0.22,
+    },
+  },
+})
+```