@talelk/newui-data 0.0.0-stage → 1.0.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,55 @@
-# 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 |
+
+## 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. 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.0.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,116 @@
+---
+name: newui-data
+description: Use the headless newui data layer for SolidJS collections,
+  repository queries, optimistic mutations, TanStack Query caching and form
+  submit lifecycles. Use when a page needs to load a list, create/update/delete
+  records, share a cache, 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.0.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
+---
+
+# 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.

package/src/download.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { csvText } from './download'
+
+describe('download', () => {
+  it('quotes every cell and doubles inner quotes', () => {
+    expect(
+      csvText([
+        ['Name', 'Note'],
+        ['Acme, Inc', 'Said "yes"'],
+        ['Globex', 42],
+      ]),
+    ).toBe('"Name","Note"\r\n"Acme, Inc","Said ""yes"""\r\n"Globex","42"')
+  })
+})

package/src/download.ts

@@ -0,0 +1,39 @@
+/**
+ * Saving a file, without the Blob/anchor/revoke dance every page wrote.
+ *
+ * `downloadCsv` quotes every cell and doubles inner quotes, which is the part
+ * that is easy to get subtly wrong.
+ */
+
+/** Save a Blob (or a local `File`) under `name`. */
+export function downloadBlob(name: string, blob: Blob): void {
+  const url = URL.createObjectURL(blob)
+  const link = document.createElement('a')
+  link.href = url
+  link.download = name
+  link.click()
+  URL.revokeObjectURL(url)
+}
+
+/** Save text under `name`; plain text unless the caller names a type. */
+export function downloadText(
+  name: string,
+  text: string,
+  mime = 'text/plain;charset=utf-8',
+): void {
+  downloadBlob(name, new Blob([text], { type: mime }))
+}
+
+/** Rows → CSV text, every cell quoted, quotes doubled. */
+export function csvText(rows: (string | number)[][]): string {
+  return rows
+    .map((row) =>
+      row.map((value) => `"${String(value).replaceAll('"', '""')}"`).join(','),
+    )
+    .join('\r\n')
+}
+
+/** Save rows as a CSV file under `name`. */
+export function downloadCsv(name: string, rows: (string | number)[][]): void {
+  downloadText(name, csvText(rows), 'text/csv;charset=utf-8')
+}

package/src/exports.test.ts

@@ -0,0 +1,105 @@
+/**
+ * The logic layer's public surface, asserted by name and by entry point.
+ *
+ * The data package has four entries (`.`, `/query`, `/form`, `/resource`),
+ * which is exactly
+ * the shape an accidental `export *` or a stray
+ * re-export slips into. An entry's cost is part of its contract — 0.77 kB for
+ * the helpers, 15.5 for the query — so a new name on an entry is a decision, not
+ * a detail.
+ */
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import * as form from './form'
+import * as root from './index'
+import * as query from './query'
+import * as resource from './resource'
+
+const ENTRIES = {
+  '.': root,
+  './query': query,
+  './form': form,
+  './resource': resource,
+} as const
+
+const SURFACE: Record<keyof typeof ENTRIES, string[]> = {
+  // Formatting, selection, undo, downloads — and nothing that renders.
+  '.': [
+    'bytes',
+    'count',
+    'createUndo',
+    'csvText',
+    'downloadBlob',
+    'downloadCsv',
+    'downloadText',
+    'first',
+    'isEmail',
+    'optionsOf',
+    'usd',
+    'usdK',
+  ],
+  './query': [
+    'DataProvider',
+    'createCollection',
+    'createDataClient',
+    'createListQuery',
+  ],
+  './form': ['Form', 'createAppForm', 'fieldError'],
+  './resource': [
+    'RequestError',
+    'createDocumentResource',
+    'createIdbStore',
+    'createListResource',
+    'createLocalStore',
+    'createRealtime',
+    'createResource',
+    'getConfig',
+    'isAbortError',
+    'normalizeError',
+    'request',
+    'resetConfig',
+    'setConfig',
+    'useCall',
+    'useDoc',
+    'useDoctype',
+    'useList',
+    'useNewDoc',
+  ],
+}
+
+const manifest = JSON.parse(
+  readFileSync(path.join(process.cwd(), 'packages/data/package.json'), 'utf8'),
+) as { exports: Record<string, unknown> }
+
+describe('@talelk/newui-data', () => {
+  it('publishes exactly the entries this test pins', () => {
+    expect(Object.keys(manifest.exports).sort()).toEqual(
+      Object.keys(ENTRIES).sort(),
+    )
+  })
+
+  for (const [entry, module] of Object.entries(ENTRIES)) {
+    it(`${entry} exports exactly its surface`, () => {
+      expect(Object.keys(module).sort()).toEqual(
+        SURFACE[entry as keyof typeof ENTRIES],
+      )
+    })
+  }
+
+  it('keeps the root entry headless', () => {
+    // The root is the only entry with no component, no query client and no
+    // validator; every value it exports is a function over plain data.
+    for (const value of Object.values(root)) {
+      expect(typeof value).toBe('function')
+    }
+  })
+
+  it('keeps the Frappe resource client off the root', () => {
+    // The DocType fetching layer is app-specific cost (fetch + IndexedDB +
+    // realtime multiplexer); it must stay behind its earned subpath.
+    for (const name of ['useDoc', 'useDoctype', 'frappeRequest', 'request']) {
+      expect(name in root).toBe(false)
+    }
+  })
+})