picocrank 1.24.0 → 1.25.1

package/AGENTS.md

@@ -5,6 +5,8 @@ PicoCrank is a Vue component library demo built on the [Femtocrank](https://gith
 ## UI patterns
 
 - [Buttons with icons](docs/buttons-with-icons.md) — Femtocrank `.inline-icon`, Hugeicons, karma variants (icon + text and icon-only).
+- [Table filterQuery v1](docs/filter-query-v1.md) — canonical remote filter wire format for `Table` / `fetchRows`.
+- Drop-in themes: `ThemeSwitcher` + `useCustomTheme()`; supplemental themes (Catppuccin, Dracula / Alucard, Gruvbox, waffles) bundled by default, loaded only when `includeSupplementalThemes` is set.
 
 ## Examples app
 

package/docs/filter-query-v1.md

@@ -0,0 +1,180 @@
+# Table filterQuery v1
+
+Canonical wire format for PicoCrank `Table` column filters. Use **`filterQuery`** in remote integrations (`fetchRows`, server persistence). The table builds this object from UI state; client-side tables apply it with `applyFilterQuery`.
+
+Implementation: [`vue/composables/tableFilterQuery.js`](../vue/composables/tableFilterQuery.js).
+
+Live reference: [`vue/examples/TableRemoteExample.vue`](../vue/examples/TableRemoteExample.vue) (`fetchRows` logs `query.filterQuery`).
+
+## Query payload
+
+Remote `fetchRows` and `@query-change` (when `fetchRows` is set) receive:
+
+```ts
+{
+  page: number
+  pageSize: number
+  sortBy: string | null
+  sortDir: 'asc' | 'desc'
+  filterQuery: FilterQueryV1
+}
+```
+
+> **Deprecation:** In **remote mode**, `filters` is **not** included in the query object. Read `filterQuery` only. Local (non-remote) `@query-change` still emits `filters` for backward compatibility; prefer `filterQuery` for new code.
+
+## FilterQueryV1 shape
+
+```json
+{
+  "version": 1,
+  "match": "all",
+  "columns": [
+    {
+      "key": "name",
+      "match": "all",
+      "filters": [
+        {
+          "id": "filter-…",
+          "name": "Managers",
+          "enabled": true,
+          "type": "text",
+          "operator": "contains",
+          "value": "Alice"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `1` | Schema version. Always `1` for v1. |
+| `match` | `'all' \| 'any'` | How to combine **columns**. `'all'` = every column group must match (AND). `'any'` = at least one column group matches (OR). UI-built queries use `'all'`. |
+| `columns` | array | Non-empty list of per-column filter groups. Unknown or non-filterable columns are dropped on normalize. |
+| `columns[].key` | string | Header `key`. |
+| `columns[].match` | `'all' \| 'any'` | How to combine **filters within the column**. `'all'` = every enabled filter must match (AND). `'any'` = at least one enabled filter matches (OR). UI-built queries use `'all'`. |
+| `columns[].filters` | array | One or more filter entries (see below). |
+
+### Filter entry fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | yes | `'text'`, `'number'`, `'boolean'`, or `'select'`. Usually matches header `filterType`. |
+| `enabled` | no | Default `true`. Disabled entries are ignored when applying. |
+| `id` | no | Stable id for UI toggling; safe to ignore on the server. |
+| `name` | no | Optional display label from the filter popover. |
+| `operator` | text/number | See operators below. |
+| `value` | text/number/boolean | Comparison value. |
+| `values` | select | Array of selected values (OR within the select filter: row value must match **any** selected value). |
+
+Inactive or invalid entries (empty text, invalid number, empty select) are omitted when the query is built from UI state.
+
+## Filter types and operators
+
+### Text (`type: 'text'`)
+
+Case-insensitive comparison on stringified cell values.
+
+| `operator` | Meaning |
+|------------|---------|
+| `contains` | Cell contains substring (default). |
+| `equals` | Cell equals string (case-insensitive). |
+| `startsWith` | Cell starts with string. |
+| `empty` | Cell is empty / whitespace only (`value` ignored). |
+
+### Number (`type: 'number'`)
+
+Numeric comparison; non-numeric cells do not match.
+
+| `operator` | Meaning |
+|------------|---------|
+| `eq` | Equal (default). |
+| `gt` | Greater than. |
+| `gte` | Greater or equal. |
+| `lt` | Less than. |
+| `lte` | Less or equal. |
+
+### Boolean (`type: 'boolean'`)
+
+| `value` | Meaning |
+|---------|---------|
+| `true` | Cell is truthy. |
+| `false` | Cell is falsy. |
+
+### Select (`type: 'select'`)
+
+| Field | Meaning |
+|-------|---------|
+| `values` | Non-empty array. Row matches if cell value equals **any** entry (strict or string-coerced equality). |
+
+## Matching semantics (summary)
+
+1. For each **column** in `columns`, evaluate enabled filters using that column’s `match` (`all` / `any`).
+2. Combine column results using top-level `match` (`all` / `any`).
+3. Columns with no active filters are ignored.
+
+Default UI behavior: **AND** across columns, **AND** across filters on the same column.
+
+## JavaScript helpers
+
+```js
+import {
+  buildFilterQuery,
+  normalizeFilterQuery,
+  applyFilterQuery,
+  filterQueryToFilters,
+  countActiveFilterQuery,
+  isFilterQueryActive,
+  cloneFilterQuery,
+  FILTER_QUERY_VERSION,
+} from '../composables/tableFilterQuery.js'
+```
+
+| Function | Purpose |
+|----------|---------|
+| `buildFilterQuery(filters, headers, rows)` | UI storage `{ [columnKey]: entries[] }` → `FilterQueryV1`. |
+| `normalizeFilterQuery(filterQuery, headers, rows)` | Validate, drop unknown columns, normalize filter specs. |
+| `applyFilterQuery(rows, headers, filterQuery)` | Client-side row filtering (same semantics as the table). |
+| `filterQueryToFilters(filterQuery, headers, rows)` | Convert back to UI storage shape (e.g. after loading from an API). |
+| `countActiveFilterQuery(filterQuery, headers, rows)` | Count enabled, active filters. |
+
+## Remote `fetchRows` example
+
+```js
+async function fetchRows(query, { signal }) {
+  // query.filterQuery — use this, not query.filters
+  const res = await api.listRows({
+    page: query.page,
+    pageSize: query.pageSize,
+    sortBy: query.sortBy,
+    sortDir: query.sortDir,
+    filterQuery: query.filterQuery,
+    signal,
+  })
+  return { rows: res.rows, total: res.total }
+}
+```
+
+To mirror client semantics in Node without reimplementing operators, reuse `applyFilterQuery` on an in-memory dataset (as in `TableRemoteExample`), or port the logic to your query layer.
+
+## Layout presets vs filterQuery
+
+Saved layouts (localStorage or `layoutPresets` callbacks) store **`filters`** (UI storage shape) inside `state`, not `filterQuery`. When a preset is applied, the table rebuilds `filterQuery` automatically. Server-side layout persistence can store either:
+
+- **`state.filters`** — round-trips the table UI exactly, or  
+- **`filterQuery`** — if you control load/save; convert with `filterQueryToFilters` before `setFilters` if needed.
+
+## Header configuration
+
+Set `filterType` on headers for remote tables (empty `:data` cannot infer types):
+
+```js
+{ key: 'age', label: 'Age', filterable: true, filterType: 'number' }
+{ key: 'city', label: 'City', filterable: true, filterType: 'select', filterOptions: […] }
+```
+
+## Versioning
+
+- **v1** (`version: 1`): current schema.  
+- Servers should ignore unknown top-level fields and reject unsupported `version` values explicitly if strict validation is required.

package/logo.svg

@@ -8,8 +8,8 @@
    sodipodi:docname="logo.svg"
    inkscape:version="1.4.2 (ebf0e940d0, 2025-05-08)"
    inkscape:export-filename="logo.png"
-   inkscape:export-xdpi="2048"
-   inkscape:export-ydpi="2048"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
    xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
    xmlns="http://www.w3.org/2000/svg"
@@ -26,12 +26,12 @@
      inkscape:pagecheckerboard="1"
      inkscape:deskcolor="#d1d1d1"
      inkscape:zoom="2"
-     inkscape:cx="114"
+     inkscape:cx="113.75"
      inkscape:cy="158.25"
-     inkscape:window-width="3840"
-     inkscape:window-height="2126"
-     inkscape:window-x="2160"
-     inkscape:window-y="2194"
+     inkscape:window-width="2160"
+     inkscape:window-height="3806"
+     inkscape:window-x="6000"
+     inkscape:window-y="514"
      inkscape:window-maximized="1"
      inkscape:current-layer="g2" />
   <g

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "picocrank",
-  "version": "1.24.0",
+  "version": "1.25.1",
   "description": "A set of zero dependency Vue components built on the Femtocrank global CSS theme.",
   "main": "vite.config.js",
   "scripts": {
+    "dev": "vite",
     "build": "vite build --base './'",
+    "build:minimal": "VITE_INCLUDE_SUPPLEMENTAL_THEMES=false vite build --base './'",
     "preview": "vite preview",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
@@ -18,12 +20,12 @@
     "url": "https://github.com/jamesread/picocrank/issues"
   },
   "dependencies": {
-    "@hugeicons/core-free-icons": "^4.2.3",
-    "@hugeicons/vue": "^1.0.7",
+    "@hugeicons/core-free-icons": "^4.3.0",
+    "@hugeicons/vue": "^1.0.8",
     "@vitejs/plugin-vue": "^6.0.8",
-    "femtocrank": "^2.5.3",
+    "femtocrank": "^2.6.1",
     "unplugin-vue-components": "^32.1.0",
-    "vite": "^8.2.1",
+    "vite": "^8.2.2",
     "vue": "^3.5.41",
     "vue-router": "^5.2.0"
   },

package/public/themes/README.md

@@ -1,6 +1,8 @@
 # Drop-in themes
 
-Themes are **not** part of the PicoCrank Vite/JS CSS bundle. Drop a folder here and restart the dev server (or rebuild) to make it discoverable.
+App themes are **not** part of the PicoCrank Vite/JS CSS bundle. Drop a folder under `public/themes/` and restart the dev server (or rebuild) to make it discoverable.
+
+**Supplemental themes** (Catppuccin Latte / Frappé, Dracula / Alucard, Gruvbox (Dark+Light), waffles) live in `supplemental-themes/` at the repo root. They are **included in the default build** but are **not listed or loaded** unless the app sets `includeSupplementalThemes: true` on `ThemeSwitcher` or `useCustomTheme()`.
 
 ## Layout
 
@@ -24,6 +26,36 @@ body {
 }
 ```
 
+For supplemental themes, use `/supplemental-themes/<name>/…`.
+
 ## Switching
 
-The examples app uses `useCustomTheme()` to list themes from `index.json` and apply the selected `theme.css` with `@import … layer(theme)`.
+Use `ThemeSwitcher` or `useCustomTheme()`:
+
+```vue
+<!-- App themes only (default) -->
+<ThemeSwitcher />
+
+<!-- Also list bundled supplemental themes -->
+<ThemeSwitcher :include-supplemental-themes="true" />
+```
+
+- `includeSupplementalThemes` (default `false`) — list and load supplemental themes when present.
+- `VITE_INCLUDE_SUPPLEMENTAL_THEMES=false` — omit supplemental theme files from `dist` (`npm run build:minimal`).
+
+Light/dark mode (header sun/moon) is separate from drop-in themes.
+
+## PicoCrank component tokens
+
+Sortable/filterable `Table` headers and `Tabs` active labels use PicoCrank aliases that point at Femtocrank semantic variables. Override the underlying Femtocrank tokens in `theme.css` rather than the aliases when possible:
+
+| PicoCrank alias | Femtocrank source |
+| --- | --- |
+| `--table-header-fg` | `--text-color` |
+| `--table-header-active-fg` | `--link-color` |
+| `--table-header-active-bg` | `--hover-background-color` |
+| `--tab-fg` | `--muted-text-color` |
+| `--tab-active-fg` | `--link-color` |
+| `--tab-focus-outline-color` | `--tab-active-fg` |
+
+Defaults are defined in `styles/picocrank-extensions.css`. Built-in dark mode and supplemental themes set Femtocrank variables (`--link-color`, `--header-fg-color`, `--input-bg-color`, etc.) so tables, tabs, forms, and chrome pick up the palette automatically.

package/public/themes/index.json

@@ -1,7 +1,3 @@
 {
-  "themes": [
-    "catppuccin",
-    "dracula",
-    "waffles"
-  ]
+  "themes": []
 }

package/styles/dark-theme.css

@@ -1,204 +1,60 @@
+/* Built-in dark mode — variable overrides only (mirrors femtocrank/dark.css). */
 @layer components {
 html[data-theme="dark"] {
-  color-scheme: dark;
+	color-scheme: dark;
 
-  --border-color: #595959;
-  --hover-background-color: #1d345c;
-  --hover-text-color: #fff;
-  --header-hover-background-color: #1d345c;
-  --standout-bg-color: #1f1f1f;
-  --disabled-background-color: #333;
-  --disabled-text-color: #999;
+	--body-bg-color: #262626;
+	--surface-bg-color: #343434;
+	--standout-bg-color: #1f1f1f;
+	--section-header-bg-color: var(--surface-bg-color);
 
-  & header {
-    background-color: black;
-    box-shadow: 0px 0px 1em #1c1c1c;
-    border-bottom: 1px solid #222;
-  }
+	--header-bg-color: #000;
+	--header-border-color: #222;
+	--header-shadow: 0px 0px 1em #1c1c1c;
+	--header-hover-background-color: #1d345c;
 
-  & body {
-    background-color: #262626;
-    color: #ddd;
-  }
+	--sidebar-bg-color: #000;
+	--sidebar-link-color: var(--link-color);
+	--sidebar-hover-bg-color: var(--hover-background-color);
 
-  & section {
-    background-color: #343434;
-    color: #ddd;
-    box-shadow: 0 0 .5em #121212;
-  }
+	--footer-chip-bg-color: #444;
 
-  & section .section-header {
-    background-color: #343434;
-    border-bottom-color: var(--border-color);
-  }
+	--text-color: #ddd;
+	--link-color: lightblue;
+	--annotation-key-color: #aaa;
+	--focus-outline-color: #fff;
 
-  & section .section-subheader {
-    border-bottom-color: var(--border-color);
-  }
+	--border-color: #595959;
+	--shadow-color: #121212;
 
-  & button,
-  & .button {
-    color: #ddd;
-    border: 1px solid var(--border-color);
-  }
+	--hover-background-color: #1d345c;
+	--hover-text-color: var(--on-accent-fg);
 
-  & button:hover,
-  & .button:hover,
-  & .button:visited {
-    background-color: var(--hover-background-color);
-    color: white;
-  }
+	--disabled-background-color: #333;
+	--disabled-text-color: #999;
 
-  & footer a,
-  & footer a:visited {
-    color: lightblue;
-  }
+	--input-bg-color: #4e4e4e;
+	--input-fg-color: var(--text-color);
+	--control-option-bg-color: #555;
+	--control-hover-bg-color: var(--hover-background-color);
 
-  & header ul[role="menubar"] a,
-  & header ul[role="menubar"] a:visited {
-    background-color: black;
-  }
+	--menu-item-hover-background-color: var(--hover-background-color);
+	--menu-dropdown-background-color: var(--surface-bg-color);
+	--menu-dropdown-shadow: 0 0 .5em var(--shadow-color);
+	--menu-dropdown-link-hover-background-color: var(--hover-background-color);
+	--header-menu-dropdown-link-hover-background-color: var(--header-hover-background-color);
 
-  & header ul[role="menubar"] a:hover {
-    background-color: var(--hover-background-color);
-  }
+	--table-sticky-bg: var(--surface-bg-color);
+	--table-row-hover-bg: var(--hover-background-color);
+	--table-row-hover-fg: var(--on-accent-fg);
+	--table-sticky-hover-bg: var(--table-row-hover-bg);
+	--table-uneditable-bg: #555;
+	--table-sticky-uneditable-bg: var(--table-uneditable-bg);
 
-  & header div > ul > li > a {
-    background-color: black;
-    color: white;
-  }
-
-  & ul[role="menubar"] div ul a:hover {
-    background-color: var(--hover-background-color);
-    color: white;
-  }
-
-  & ul[role="menubar"] li:hover {
-    background-color: var(--hover-background-color);
-  }
-
-  & label:has(input[type="checkbox"]):hover,
-  & label:has(input[type="radio"]):hover {
-    background-color: var(--hover-background-color);
-    color: white;
-  }
-
-  & label:has(input:checked) {
-    background-color: #488448;
-    color: white;
-  }
-
-  & label:has(input:checked):hover {
-    background-color: #3a6f3a;
-    color: white;
-  }
-
-  & a,
-  & a:visited,
-  & aside a,
-  & aside a:visited {
-    color: lightblue;
-  }
-
-  & table,
-  & th,
-  & td {
-    border-color: var(--border-color) !important;
-  }
-
-  & table.row-hover tr:hover td {
-    background-color: var(--hover-background-color);
-    color: white;
-  }
-
-  & footer span {
-    background-color: #444;
-  }
-
-  & input[type="text"],
-  & input[type="email"],
-  & input[type="password"],
-  & input[type="url"],
-  & input[type="number"],
-  & input[type="color"],
-  & input[type="datetime-local"] {
-    background-color: #4e4e4e;
-    color: #ddd;
-    border-color: var(--border-color);
-  }
-
-  & select {
-    background-color: #4e4e4e;
-    color: #ddd;
-    border-color: var(--border-color);
-  }
-
-  & textarea {
-    background-color: #4e4e4e;
-    color: #ddd;
-    border-color: var(--border-color);
-  }
-
-  & .grid-boxed .stat-display {
-    background-color: var(--standout-bg-color);
-    border-color: var(--border-color) !important;
-  }
-
-  & pre {
-    background-color: var(--standout-bg-color);
-    color: #ddd;
-    border: 1px solid var(--border-color);
-  }
-
-  & .radio-group {
-    border-color: var(--border-color);
-  }
-
-  & .radio-group label {
-    background-color: #555;
-  }
-
-  & .radio-group label:hover,
-  & .radio-group label:has(input:focus-visible) {
-    background-color: var(--hover-background-color);
-    color: white;
-  }
-
-  & .multiple-checklist {
-    border-color: var(--border-color);
-  }
-
-  & .multiple-checklist label {
-    background-color: #555;
-  }
-
-  & aside {
-    background-color: #000;
-    box-shadow: 0 0 .5em #121212;
-  }
-
-  & aside :is(ul, menu) li a:hover {
-    background-color: var(--hover-background-color);
-  }
-
-  & dt {
-    border-color: var(--border-color);
-  }
-
-  & .annotation,
-  & .tag,
-  & .inline-notification {
-    background-color: var(--standout-bg-color);
-    color: #ddd;
-    border-color: var(--border-color);
-  }
-
-  & .annotation-val {
-    color: #ddd;
-  }
-}
+	--progress-track-bg-color: var(--table-uneditable-bg);
 }
 
 html[data-theme="light"] {
-  color-scheme: light;
+	color-scheme: light;
+}
 }

package/styles/picocrank-extensions.css

@@ -0,0 +1,15 @@
+/* PicoCrank component tokens — aliases to Femtocrank semantic variables. */
+@layer components {
+:root {
+	--table-header-fg: var(--text-color);
+	--table-header-active-fg: var(--link-color);
+	--table-header-active-bg: var(--hover-background-color);
+	--tab-fg: var(--muted-text-color);
+	--tab-active-fg: var(--link-color);
+	--tab-focus-outline-color: var(--tab-active-fg);
+}
+
+table thead th {
+	color: var(--table-header-fg);
+}
+}

package/styles.css

@@ -2,6 +2,7 @@
 @layer components, karma, theme;
 
 @import 'femtocrank/style.css' layer(components);
+@import './styles/picocrank-extensions.css';
 @import './styles/dark-theme.css';
 
 /* Sidebar uses <menu> for nav items; mirror Femtocrank's aside ul rules. */

package/supplemental-themes/README.md

@@ -0,0 +1,9 @@
+# PicoCrank supplemental themes
+
+Optional drop-in themes (Catppuccin Latte / Frappé, Dracula / Alucard, Gruvbox (Dark+Light), waffles) shipped alongside the default build unless disabled.
+
+- **Build / dev assets:** included by default. Set `VITE_INCLUDE_SUPPLEMENTAL_THEMES=false` for a minimal build (`npm run build:minimal`).
+- **Runtime:** opt in with `includeSupplementalThemes` on `ThemeSwitcher` or `useCustomTheme()` (default `false`). Client apps do not list or apply these themes unless explicitly enabled.
+- **Catppuccin Latte / Frappé:** one theme folder (`catppuccin-latte-frappe`); header light/dark toggle switches between Latte (light) and Frappé (dark).
+- **Gruvbox (Dark+Light):** one theme folder (`gruvbox-dark-light`); header light/dark toggle switches between Gruvbox Dark and Light.
+- **Dracula / Alucard:** one theme folder (`dracula-alucard`); header light/dark toggle switches between Dracula (dark) and Alucard (light).