@talelk/newui-data 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @talelk/newui-data
 
-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.
+The logic layer: the things every app does the same way and no two agree on
+when they write them themselves.
+
+```ts
+import { createUndo, downloadCsv, usd, optionsOf } from '@talelk/newui-data'
+```
+
+The package is **headless** — it imports `solid-js` for signals and nothing from
+the visual packages, so a page can use it without paying for a component, and a
+component can never reach up into it. What renders stays in the atomic packages;
+this level only answers *how it behaves*.
+
+The first four surfaces are the ones the examples had already copied:
+
+| surface | what it owns |
+| --- | --- |
+| `format` | `usd`, `usdK`, `count`, `bytes`, `isEmail` — one `Intl` formatter each, built once |
+| `select` | `optionsOf`, `first` — the `{ label, value }` plumbing and the empty-array unwrap |
+| `undo` | `createUndo` — a snapshot, a restore and a clear, without the page's notice copy |
+| `download` | `downloadBlob`, `downloadText`, `downloadCsv`, `csvText` — the Blob/anchor/revoke dance and RFC-shaped quoting |
+
+The analytics primitives, decided in issues #22, #23, #24 and #32, round out the
+headless layer:
+
+| surface | what it owns |
+| --- | --- |
+| `url-state` | `createUrlState` — link-reproducible signals behind a router adapter, replace-not-push, debounced search keys |
+| `config-store` | `createConfigStore` — versioned envelopes for saved views and dashboard config over a storage seam |
+| `aggregate` | `aggregate`, `timeBucket`, `rollup` — pure group-by and time-series transforms over rows the app already fetched |
+
+## Query
+
+```tsx
+import { DataProvider, createCollection } from '@talelk/newui-data/query'
+
+const tasks = createCollection(() => ({
+  key: ['tasks'],
+  repository,               // list / create / update / remove
+}))
+
+tasks.query.rows()
+tasks.update.mutate({ id, patch })   // optimistic, reversible
+```
+
+The query surface is its own entry point, so importing `usd` never pulls a
+cache in. `DataProvider` owns the client (and clears it on unmount);
+`createCollection` returns one list query and four mutations, each refreshing
+the list on settle so a mutation and the Refresh button cannot disagree.
+
+TanStack Query and Form are dependencies of this package; the app does not
+depend on them directly. Rendered `DataTable` and `VirtualList` are organisms
+and `ScrollTable` is a molecule. This package supplies their headless data
+behavior, not their rendered surface; `spec/data.md` is the contract for what
+has shipped.
+
+## Resource — `@talelk/newui-data/resource`
+
+The Frappe DocType client: `request`/`frappeRequest` transport with
+`setConfig`, document and list hooks (`useDoc`, `useDoctype`, `useList`,
+`useNewDoc`, `useCall`), an IndexedDB cache, and a shared WebSocket realtime
+multiplexer (`createRealtime`, plus `connectRealtime` to invalidate query keys
+from socket events). It lives behind its own entry so importing `usd` never
+pulls a fetch stack, and it is app-specific — generic query needs belong on
+`/query`.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@talelk/newui-data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "type": "module",
+  "description": "The logic layer: formatting, selection, undo and downloads — no components.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/talelk/newui.git",
+    "directory": "packages/data"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./query": {
+      "types": "./src/query/index.ts",
+      "default": "./src/query/index.ts"
+    },
+    "./form": {
+      "types": "./src/form/index.ts",
+      "default": "./src/form/index.ts"
+    },
+    "./resource": {
+      "types": "./src/resource/index.ts",
+      "default": "./src/resource/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "skills"
+  ],
+  "keywords": [
+    "tanstack-intent",
+    "agent-skills",
+    "solidjs",
+    "data"
+  ],
+  "peerDependencies": {
+    "solid-js": "^1.9.0"
+  },
+  "devDependencies": {
+    "solid-js": "^1.9.0"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@tanstack/solid-form": "^1.33.5",
+    "@tanstack/solid-query": "^5.104.3"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }

package/skills/newui-data/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: newui-data
+description: Use the headless newui data layer for SolidJS collections,
+  repository queries, optimistic mutations, TanStack Query caching, form submit
+  lifecycles, URL-synced state, saved-view/dashboard-config storage and
+  aggregation/rollup transforms. Use when a page needs to load a list,
+  create/update/delete records, share a cache, sync filters or views to the URL,
+  persist saved views, build chart series, or wire TanStack Form through the
+  kit's Form and field-error contract.
+metadata:
+  type: core
+  domain: data
+  library: '@talelk/newui-data'
+  library_version: '1.1.0'
+sources:
+  - talelk/newui:spec/data.md
+  - talelk/newui:skills/README.md
+  - talelk/newui:packages/data/README.md
+  - talelk/newui:packages/data/src/query/client.tsx
+  - talelk/newui:packages/data/src/query/collection.ts
+  - talelk/newui:packages/data/src/query/repository.ts
+  - talelk/newui:packages/data/src/form/form.tsx
+  - talelk/newui:packages/data/src/url-state.ts
+  - talelk/newui:packages/data/src/config-store.ts
+  - talelk/newui:packages/data/src/aggregate.ts
+  - talelk/newui:packages/data/src/resource/connect-realtime.ts
+---
+
+# newui-data
+
+The headless data layer: one query client, one collection abstraction and one
+form surface. It renders nothing. Load the `newui` skill as well when the page
+needs components.
+
+## Wire the client once
+
+```tsx no-check
+import { DataProvider } from '@talelk/newui-data/query'
+
+export function App() {
+  return <DataProvider>{/* router and pages */}</DataProvider>
+}
+```
+
+`DataProvider` owns a `QueryClient` and clears it on unmount. Pass `client` to
+share one across panes. The defaults are deliberate: no refetch on window focus,
+one retry, and errors are data the page renders rather than exceptions.
+
+## Collections
+
+A repository is the only place that knows where records come from. A collection
+turns it into one cached list and four optimistic mutations.
+
+```tsx
+import { createCollection } from '@talelk/newui-data/query'
+
+const projects = createCollection<Project, NewProject>(() => ({
+  key: ['projects'],
+  repository: projectRepository,
+  onError: (error) => setNotice(error.message),
+}))
+
+projects.query.rows()
+projects.query.isPending()
+projects.query.isError()
+projects.create.mutateAsync(input)
+projects.update.mutateAsync({ id, patch })
+projects.updateMany.mutate({ ids, patch })
+projects.remove.mutateAsync({ ids })
+```
+
+- Read `collection.query.rows()`; never reach into the cache from a page.
+- `create` is not optimistic because the repository owns the new id and defaults.
+- `update`, `updateMany` and `remove` land immediately and roll back on failure.
+- Mutations resolve after the list refresh settles, so a page can close its
+  dialog in the same `await`.
+- Repositories receive an `AbortSignal`; honour it or superseded list requests
+  can resurrect stale rows.
+
+## Forms
+
+```tsx no-check
+import { createAppForm, fieldError, Form } from '@talelk/newui-data/form'
+
+const { form, submitting } = createAppForm({
+  defaultValues: { name: '' },
+  onSubmit: async (value) => {
+    await projects.create.mutateAsync({ name: value.name })
+  },
+})
+
+<Form form={form}>
+  <form.Field
+    name="name"
+    validators={{
+      onChange: ({ value }) =>
+        value.trim().length < 2 ? 'Give the project a name.' : undefined,
+    }}
+  >
+    {(field) => (
+      <TextInput
+        label="Name"
+        required
+        value={field().state.value}
+        error={fieldError(field())}
+        onInput={(event) => field().handleChange(event.currentTarget.value)}
+      />
+    )}
+  </form.Field>
+  <Button type="submit" loading={submitting()}>
+    Create
+  </Button>
+</Form>
+```
+
+- `createAppForm` owns TanStack Form and exposes `submitting()` for the button.
+- `Form` sets `noValidate` and prevents the native submit; field messages are the
+  error UI.
+- `fieldError` maps TanStack's error list to the single string `Field` takes and
+  de-duplicates the same validator message.
+- Pass the same message to `onChange` and `onSubmit` when the field should
+  validate on both; `fieldError` will not print it twice.
+
+### Config forms: the field map, pruning and autosave
+
+- `createAppForm({ schema, ui, pruneHidden })` takes a Standard Schema and a
+  **field map** (`ui`) keyed by *static* paths (`smtp.host`, never `items[1]`
+  — that throws; a repeater's row fields go under its `fields`). Pass the same
+  object to the `ConfigForm` organism's `fields`.
+- `when(scope, values)` hides a field: `scope` is the form values for a
+  top-level entry and **the row** for a repeater's row field. Hidden fields
+  are pruned from the submitted document (`pruneHidden` defaults to `true`),
+  and schema issues under them never block submit.
+- `app.document(values)` is that submitted document. Give
+  `createAutoSave(app, { save, id })` the `createAppForm` result, not
+  `app.form`, so autosave writes the same pruned document submit sends.
+- With `id`, autosave keeps a local, unpruned **draft**; a successful autosave
+  or submit drops it. `restoreDraft()` is untrusted input (it may predate the
+  schema) — reset the form with it and let validation report what no longer
+  fits.
+
+## URL state, saved views and transforms
+
+```ts
+import { createConfigStore, createUrlState, rollup } from '@talelk/newui-data'
+
+// Link-reproducible state; the app owns the router through `adapter`.
+const filters = createUrlState(
+  { 'board.view': 'kanban', q: '' },
+  { adapter, debounce: ['q'] },
+)
+filters['board.view']()
+filters.set('q', 'invoice') // undefined = absent, never ""
+
+// Saved views and dashboard configs: versioned envelopes, storage-agnostic.
+const views = createConfigStore({ key: 'acme.views' })
+views.save('week-only', { filters: [] }, { type: 'saved-view' })
+
+// Chart series from a time column — pure, no query, no components.
+const series = rollup(rows, { field: 'createdAt', unit: 'day', metric: { field: 'amount', metric: 'sum' } })
+```
+
+- `createUrlState` reads the URL once on mount and **replaces** (never pushes);
+  without an adapter it is a plain signal, so tests and SSR stay clean.
+- `createConfigStore` documents are capped at 64KB with a dev warning; a
+  server-backed adapter drops in by passing `storage`, no consumer changes.
+- `aggregate`/`rollup` run over rows the app already fetched — past that size
+  the answer is server-side, not a client pivot.
+- A collection can poll with `refetchInterval`; `connectRealtime` (from
+  `@talelk/newui-data/resource`) invalidates query keys from socket events.