picocrank 1.23.1 → 1.25.0

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.23.1",
+  "version": "1.25.0",
   "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.0",
     "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,21 @@ 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.

package/public/themes/index.json

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

package/styles/dark-theme.css

@@ -5,6 +5,7 @@ html[data-theme="dark"] {
   --border-color: #595959;
   --hover-background-color: #1d345c;
   --hover-text-color: #fff;
+  --text-color: #ddd;
   --header-hover-background-color: #1d345c;
   --standout-bg-color: #1f1f1f;
   --disabled-background-color: #333;
@@ -111,6 +112,18 @@ html[data-theme="dark"] {
     color: white;
   }
 
+  & table thead th.sortable:hover,
+  & table thead th.filtered,
+  & table thead th.menu-open {
+    color: var(--text-color);
+  }
+
+  & th.actions .actions-menu-trigger button:hover,
+  & th.actions .actions-menu-trigger button:focus-visible {
+    background-color: var(--hover-background-color);
+    color: var(--text-color);
+  }
+
   & footer span {
     background-color: #444;
   }
@@ -177,8 +190,10 @@ html[data-theme="dark"] {
     box-shadow: 0 0 .5em #121212;
   }
 
-  & aside :is(ul, menu) li a:hover {
+  & aside :is(ul, menu) li a:hover,
+  & aside :is(ul, menu) li a:focus-visible {
     background-color: var(--hover-background-color);
+    color: var(--hover-text-color, #fff);
   }
 
   & dt {

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).

package/supplemental-themes/catppuccin-latte-frappe/theme.css

@@ -0,0 +1,276 @@
+/*
+ * Catppuccin Latte / Frappé supplemental theme for PicoCrank / Femtocrank.
+ * Palette: https://catppuccin.com/palette/
+ *
+ * Light mode (header toggle) uses Latte; dark mode uses Frappé.
+ *
+ * Asset URLs must be absolute, e.g.:
+ *   background-image: url('/supplemental-themes/catppuccin-latte-frappe/background.png');
+ */
+
+html[data-theme="dark"] {
+	color-scheme: dark;
+
+	--ctp-rosewater: #f2d5cf;
+	--ctp-flamingo: #eebebe;
+	--ctp-pink: #f4b8e4;
+	--ctp-mauve: #ca9ee6;
+	--ctp-red: #e78284;
+	--ctp-maroon: #ea999c;
+	--ctp-peach: #ef9f76;
+	--ctp-yellow: #e5c890;
+	--ctp-green: #a6d189;
+	--ctp-teal: #81c8be;
+	--ctp-sky: #99d1db;
+	--ctp-sapphire: #85c1dc;
+	--ctp-blue: #8caaee;
+	--ctp-lavender: #babbf1;
+	--ctp-text: #c6d0f5;
+	--ctp-subtext1: #b5bfe2;
+	--ctp-subtext0: #a5adce;
+	--ctp-overlay2: #949cbb;
+	--ctp-overlay1: #838ba7;
+	--ctp-overlay0: #737994;
+	--ctp-surface2: #626880;
+	--ctp-surface1: #51576d;
+	--ctp-surface0: #414559;
+	--ctp-base: #303446;
+	--ctp-mantle: #292c3c;
+	--ctp-crust: #232634;
+	--ctp-shadow: rgba(35, 38, 52, 0.65);
+	--ctp-shadow-strong: rgba(35, 38, 52, 0.9);
+	--ctp-good-fg: var(--ctp-crust);
+
+	--text-color: var(--ctp-text);
+	--border-color: var(--ctp-surface1);
+	--standout-bg-color: var(--ctp-mantle);
+	--hover-background-color: var(--ctp-surface0);
+	--hover-text-color: var(--ctp-text);
+	--header-hover-background-color: var(--ctp-surface1);
+	--header-hover-text-color: var(--ctp-text);
+	--header-text-color: var(--ctp-text);
+	--disabled-background-color: var(--ctp-surface0);
+	--disabled-text-color: var(--ctp-overlay0);
+
+	--karma-good: var(--ctp-green);
+	--karma-bad: var(--ctp-red);
+	--karma-warning: var(--ctp-yellow);
+	--karma-severe: var(--ctp-maroon);
+	--karma-important: var(--ctp-peach);
+	--karma-note: var(--ctp-sapphire);
+	--karma-info: var(--ctp-surface1);
+	--karma-old: var(--ctp-overlay0);
+
+	--karma-good-fg: var(--ctp-green);
+	--karma-bad-fg: var(--ctp-red);
+	--karma-warning-fg: var(--ctp-yellow);
+	--karma-severe-fg: var(--ctp-maroon);
+	--karma-important-fg: var(--ctp-peach);
+	--karma-note-fg: var(--ctp-sapphire);
+	--karma-info-fg: var(--ctp-subtext0);
+	--karma-old-fg: var(--ctp-overlay1);
+}
+
+html[data-theme="light"] {
+	color-scheme: light;
+
+	--ctp-rosewater: #dc8a78;
+	--ctp-flamingo: #dd7878;
+	--ctp-pink: #ea76cb;
+	--ctp-mauve: #8839ef;
+	--ctp-red: #d20f39;
+	--ctp-maroon: #e64553;
+	--ctp-peach: #fe640b;
+	--ctp-yellow: #df8e1d;
+	--ctp-green: #40a02b;
+	--ctp-teal: #179299;
+	--ctp-sky: #04a5e5;
+	--ctp-sapphire: #209fb5;
+	--ctp-blue: #1e66f5;
+	--ctp-lavender: #7287fd;
+	--ctp-text: #4c4f69;
+	--ctp-subtext1: #5c5f77;
+	--ctp-subtext0: #6c6f85;
+	--ctp-overlay2: #7c7f93;
+	--ctp-overlay1: #8c8fa1;
+	--ctp-overlay0: #9ca0b0;
+	--ctp-surface2: #acb0be;
+	--ctp-surface1: #bcc0cc;
+	--ctp-surface0: #ccd0da;
+	--ctp-base: #eff1f5;
+	--ctp-mantle: #e6e9ef;
+	--ctp-crust: #dce0e8;
+	--ctp-shadow: rgba(76, 79, 105, 0.12);
+	--ctp-shadow-strong: rgba(76, 79, 105, 0.16);
+	--ctp-good-fg: var(--ctp-base);
+
+	--text-color: var(--ctp-text);
+	--border-color: var(--ctp-surface1);
+	--standout-bg-color: var(--ctp-mantle);
+	--hover-background-color: var(--ctp-surface0);
+	--hover-text-color: var(--ctp-text);
+	--header-hover-background-color: var(--ctp-surface0);
+	--header-hover-text-color: var(--ctp-text);
+	--header-text-color: var(--ctp-text);
+	--disabled-background-color: var(--ctp-surface0);
+	--disabled-text-color: var(--ctp-overlay0);
+
+	--karma-good: var(--ctp-green);
+	--karma-bad: var(--ctp-red);
+	--karma-warning: var(--ctp-yellow);
+	--karma-severe: var(--ctp-maroon);
+	--karma-important: var(--ctp-peach);
+	--karma-note: var(--ctp-sapphire);
+	--karma-info: var(--ctp-surface1);
+	--karma-old: var(--ctp-overlay0);
+
+	--karma-good-fg: var(--ctp-green);
+	--karma-bad-fg: var(--ctp-red);
+	--karma-warning-fg: var(--ctp-yellow);
+	--karma-severe-fg: var(--ctp-maroon);
+	--karma-important-fg: var(--ctp-peach);
+	--karma-note-fg: var(--ctp-sapphire);
+	--karma-info-fg: var(--ctp-subtext0);
+	--karma-old-fg: var(--ctp-overlay1);
+}
+
+body {
+	background-color: var(--ctp-base);
+	color: var(--ctp-text);
+}
+
+header {
+	background-color: var(--ctp-crust);
+	border-bottom: 1px solid var(--ctp-surface0);
+	box-shadow: none;
+	color: var(--ctp-text);
+}
+
+header a,
+header a:visited,
+header button,
+header .button,
+header h1,
+header .topbar-link,
+header .topbar-link:visited {
+	color: var(--header-text-color, var(--ctp-text));
+}
+
+#sidebar-toggler-button,
+#sidebar-toggler-button.neutral,
+header .theme-toggle,
+header .theme-toggle.neutral,
+header .search-trigger,
+header .search-trigger.neutral,
+header .user-info {
+	background-color: transparent;
+	border: 0;
+	color: var(--header-text-color, var(--ctp-text));
+}
+
+#sidebar-toggler-button:hover,
+header .theme-toggle:hover,
+header .search-trigger:hover,
+header .user-info:hover {
+	background-color: var(--header-hover-background-color);
+	color: var(--header-hover-text-color);
+}
+
+aside,
+#sidebar {
+	background-color: var(--ctp-mantle);
+	color: var(--ctp-text);
+	border-color: var(--ctp-surface0);
+	box-shadow: 0.15em 0 0.6em var(--ctp-shadow);
+}
+
+aside a,
+aside a:visited {
+	color: var(--ctp-text);
+}
+
+aside a:hover,
+aside a:focus-visible,
+aside :is(ul, menu) li a:hover,
+aside :is(ul, menu) li a:focus-visible,
+aside .nav-section-header:hover,
+aside .nav-section-header:focus-visible {
+	background-color: var(--ctp-surface0);
+	color: var(--ctp-text);
+}
+
+section {
+	background-color: var(--ctp-mantle);
+	color: var(--ctp-text);
+	box-shadow: 0 0 0.5em var(--ctp-shadow-strong);
+	border-color: var(--ctp-surface0);
+}
+
+section .section-header,
+section .section-subheader {
+	background-color: var(--ctp-mantle);
+	border-bottom-color: var(--ctp-surface0);
+	color: var(--ctp-text);
+}
+
+button,
+.button {
+	background-color: var(--ctp-surface0);
+	border: 1px solid var(--ctp-surface1);
+	color: var(--ctp-text);
+}
+
+button:hover,
+.button:hover {
+	background-color: var(--ctp-surface1);
+	color: var(--ctp-text);
+}
+
+button.good,
+.button.good {
+	background-color: var(--ctp-green);
+	border-color: var(--ctp-green);
+	color: var(--ctp-good-fg);
+}
+
+button.bad,
+.button.bad {
+	background-color: var(--ctp-red);
+	border-color: var(--ctp-red);
+	color: var(--ctp-crust);
+}
+
+button.warning,
+.button.warning {
+	background-color: var(--ctp-yellow);
+	border-color: var(--ctp-yellow);
+	color: var(--ctp-crust);
+}
+
+button.neutral,
+.button.neutral {
+	background-color: var(--ctp-surface1);
+	border-color: var(--ctp-surface2);
+	color: var(--ctp-text);
+}
+
+input,
+select,
+textarea {
+	background-color: var(--ctp-surface0);
+	border: 1px solid var(--ctp-surface1);
+	color: var(--ctp-text);
+}
+
+a {
+	color: var(--ctp-blue);
+}
+
+footer {
+	color: var(--ctp-subtext0);
+	border-top-color: var(--ctp-surface0);
+}
+
+.subtle {
+	color: var(--ctp-subtext0);
+}