foldkit-form-recipes 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Glenn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,295 @@
-# Temporary Holding Version
+# foldkit-form-recipes
 
-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.
+Field recipes for [`foldkit-form`](../form/README.md). A recipe is what one kind
+of key means: a **control**, which reads a draft into the key's value and shows a
+stored value as a draft, and a **display**, which reads the value in a list or a
+detail. Both are made from the same options, so a date reads the same in its
+field and in its table cell, and the parsing that is easy to get quietly wrong
+(a date typed month-first, a time the clocks skip) is written once.
+
+## What it owns
+
+| Fact | Owner |
+| --- | --- |
+| The key's schema, and so what a valid value is | your input schema |
+| The drafts, their validity, and the submit | `foldkit-form` |
+| How a draft becomes a value and a value a draft; how a value reads in a list | **this package** |
+| The element that edits it | `foldkit-form-recipes/html` (or your own renderer) |
+
+A recipe owns no state and sends no Message, except `image`, whose control
+holds its upload (below). It attaches where any control does: a form's `inputs`, or Entity metadata through `Input.of` and `Display.of`.
+
+## Mental model
+
+```text
+stored value --format--> draft (what the input shows)
+draft (typed) --parse--> value --schema--> valid, or the key's error
+```
+
+`format` runs only when the form is filled, never on a keystroke, so the caret
+and a composition survive typing. A draft `parse` cannot read is the recipe's
+own error (`Enter a date`); an empty one is the form's (`Required`, or nothing
+for an optional key).
+
+## Install
+
+```sh
+pnpm add foldkit-form-recipes foldkit-form foldkit-crud
+# and, for the plain renderers:
+pnpm add foldkit-mixins-form
+```
+
+## Sixty seconds
+
+```ts
+import { Schema } from 'effect'
+import { Form } from 'foldkit-form'
+import { FieldRecipes } from 'foldkit-form-recipes'
+import { renderers } from 'foldkit-form-recipes/html'
+import { FormView } from 'foldkit-mixins-form'
+import { CalendarDate } from 'foldkit/calendar'
+
+const due = FieldRecipes.date()
+const startsAt = FieldRecipes.dateTime({ stored: 'instant', zone: 'Europe/London' })
+
+const Meeting = Form.make(
+  'Meeting',
+  Form.input(Schema.Struct({ due: CalendarDate, startsAt: Schema.String })),
+  { inputs: { due: due.control, startsAt: startsAt.control } },
+)
+
+const View = FormView.define(Meeting, { renderers: renderers() })
+```
+
+`due.control` and `startsAt.control` are plain `foldkit-form` controls: they do
+no I/O and hold no state. `renderers()` draws them as `input type="date"` and
+`type="datetime-local"`, named by their keys, so a post without scripts carries
+the drafts. Filled with `{ due: Calendar.make(2026, 7, 1), startsAt:
+'2026-07-01T08:30:00.000Z' }`, the inputs read `2026-07-01` and
+`2026-07-01T09:30`, London being an hour ahead in July; typing `2026-07-01T09:30`
+submits `'2026-07-01T08:30:00.000Z'`.
+
+## The recipes
+
+### `date(options?)`
+
+A key whose value is a `CalendarDate`: `Calendar.CalendarDate`, or
+`Calendar.CalendarDateFromIsoString` to store it as text. The draft is the
+`YYYY-MM-DD` a date input writes. Anything else, a partly typed date, a day
+first, or 30 February, reads `Enter a date`.
+
+### `dateTime({ stored, zone?, locale? })`
+
+A date and a time, stored in one of two forms, chosen explicitly:
+
+- **`stored: 'local'`**: the key's value is the wall-clock text a
+  `datetime-local` input writes (`2026-10-26T09:30`), in no zone. It is kept as
+  typed, so a stored value comes back unchanged. Use it for a time that means a
+  clock reading wherever it is read: a shop's opening hour.
+- **`stored: 'instant', zone`**: the value is an ISO instant with an offset, and
+  the draft is what the clocks in `zone` (an IANA name such as `Europe/London`)
+  read at it. A submitted value is written as `Date.prototype.toISOString` writes
+  one; any offset is read. An unknown zone throws when the recipe is made.
+
+The zone is a parameter, never the runtime's, so a server and a browser fill the
+same text. To follow the person's own zone, pass it:
+`Intl.DateTimeFormat().resolvedOptions().timeZone`.
+
+`locale` (default `en`) is what a display says the value in. It changes no
+draft: the inputs' text is the same in every locale.
+
+### Text-shaped keys
+
+Each keeps what was typed, unchanged: none trims, lower-cases or rewrites it.
+Their renderers give the input its type, what the browser may fill it with, and
+turn off capitalization and spelling correction where a correction would be a
+wrong address.
+
+| Recipe | Takes | Input |
+| --- | --- | --- |
+| `email({ autocomplete? })` | one `@`, something either side, no space; else `Enter an email address` | `type="email"`, `autocomplete="email"` |
+| `url({ protocols?, autocomplete? })` | an address that parses with a scheme in `protocols` (default `https:`, `http:`), so `javascript:` is refused | `type="url"` |
+| `tel({ autocomplete? })` | anything: a number is too varied to check without refusing a real one, so leave it to the schema | `type="tel"`, `inputmode="tel"` |
+| `password({ purpose })` | anything | `type="password"`, `autocomplete` `current-password` or `new-password` |
+| `slug(from, { prefix?, through? })` | anything | a text input after `prefix` |
+
+A `slug` follows the key `from`, made into a slug by `through` (default
+`FieldRecipes.slugify`: lower case, unaccented, `ß` as `ss` and `ı` as `i`, words
+joined by `-`; a script with no Latin spelling, such as `東京`, leaves nothing,
+so such a title's slug is written by hand), until the
+person writes it; a form filled with a stored slug does not follow, so a
+published address does not move because its title did. Its control is a
+`ControlChange`, which only a form's `inputs` takes.
+
+A `password` never shows in a list (its display is hidden) and has no reveal
+toggle: whether the text shows is state the form does not hold, and
+`foldkit-mixins-ui`'s `PasswordInput` keeps it in the application. Keep a
+password out of any saved draft: a form cannot leave a key out of `partial()`,
+so that rule is the application's.
+
+### Amounts: `money`, `decimal`, `percent`
+
+```ts
+const price = FieldRecipes.money({ currency: 'EUR', unit: 'minor', locale: 'de-DE' })
+const weight = FieldRecipes.decimal({ scale: 3 })
+const discount = FieldRecipes.percent({ unit: 'fraction' })
+```
+
+An amount is read and shown as `locale` writes it, and built from its digits, so
+no floating point stands between what was typed and what is stored:
+
+- **`money({ currency, unit, locale?, negative? })`**: `unit: 'minor'` stores an
+  integer of the currency's smallest unit (`123456` for 1.234,56 €), `'decimal'` a
+  decimal text (`'1234.56'`); the key's schema says which, and a value of the other
+  form fails the fill rather than being converted. The currency sets the decimals:
+  none for JPY, three for KWD. A filled field shows `1.234,56 €`, and typing
+  `1.234,56` or `1234,56` reads the same.
+- **`decimal({ scale, locale?, negative? })`**: a number with at most `scale`
+  decimals.
+- **`percent({ unit, scale?, locale?, negative? })`**: shown as `12.5%`, stored as
+  the share (`unit: 'fraction'`, `0.125`) or the points (`'points'`, `12.5`).
+
+What is refused rather than guessed at: grouping other than the locale's (`12,3`
+in `en-US` is not `123`, and `12.3` in `de-DE` is not either), more decimals than
+the scale (never rounded), a minus unless `negative: true`, a space inside an
+amount where the locale groups with none, a symbol anywhere but at either end,
+a minor amount past what a JavaScript number holds exactly (use `'decimal'` for
+those), and a `decimal` or `percent` a JavaScript number would round. A partial
+amount (`-`, or `1,2` in `en-US`) reads `Enter an amount`: the form checks a key
+as it changes. What a keyboard types for what a format writes is read alike: `¥`
+for `￥`, `'` for the Swiss `’`, full-width digits and punctuation, and the bidi
+marks an rtl locale writes around an amount are not part of it. Nothing else is
+folded: `10²` and `①②` are refused rather than read as `102` and `12`, and so is
+an amount holding an override or a zero-width space, which would show one
+number and mean another. The inputs are text with a numeric keypad (`inputmode`), since `"4."`
+is a fine draft that `type="number"` would refuse to report.
+
+### Drawn through `foldkit-mixins-ui`
+
+`foldkit-form-recipes/ui`'s `renderers({ input? })` draws the same native inputs
+under `foldkit-mixins-ui`'s Input Slot, for a form drawn with
+`foldkit-mixins-form/ui`'s table:
+
+```ts
+import { renderers as uiRecipes } from 'foldkit-form-recipes/ui'
+import { Style } from 'foldkit-mixins'
+import * as UiForm from 'foldkit-mixins-form/ui'
+import { InputSlots, Recipes } from 'foldkit-mixins-ui'
+
+const input = Style.forSlots(InputSlots)(Recipes.Input())
+const UiView = FormView.define(Meeting, {
+  renderers: { ...UiForm.renderers({ input }), ...uiRecipes({ input }) },
+})
+```
+
+The inputs, their names and their Messages are the plain ones; only the look is
+the Input recipe's. A calendar in a popover is not one of them: it holds an open
+month and a focused day, state a renderer has nowhere to keep, so it would be a
+control backed by a Bundle, as `image` is, and is not built.
+
+### An image: `foldkit-form-recipes/image`
+
+`image({ id, url?, headers?, words?, styles? })` is a key whose value is the
+`HashedAsset` that `foldkit-media`'s upload route answers. Its control is a
+Bundle, because an upload has state of its own:
+
+```text
+Empty --choose--> Sending --201--> Kept (the value)
+                  Sending --cancel--> Empty
+                  Sending --refused--> Refused --retry--> Sending
+                                       Refused --choose--> Sending
+Sending, Refused, Kept --remove--> Empty
+```
+
+```ts
+import { image } from 'foldkit-form-recipes/image'
+import { HashedAsset } from 'foldkit-media'
+
+const cover = image({ id: 'cover' })
+const Post = Form.make('Post', Form.input(Schema.Struct({ cover: HashedAsset })), {
+  inputs: { cover: cover.control },
+})
+```
+
+Choosing a file (dropped, or picked through the drop zone's input) sends it at
+once with `foldkit-media/browser`'s `upload`. The control draws its progress and
+a Cancel button, which ends the send's Subscription and so aborts the request.
+A refusal shows the route's reason (`words.refused`) with Try again, which
+sends the same file again. Only `Kept` is a value: a file on its way, or
+refused, is nothing entered.
+
+- **A submit while a file is on its way** waits for it (the control is `busy`
+  while `Sending`): the key reads as being checked, the form says
+  `words.checking` under it, and the submit goes out with the image once the
+  route keeps it. A cancel or a refusal ends the wait with nothing submitted, a
+  required key then saying `Required`.
+- **Who may upload** stays the route's `UploadPolicy`, which a page's session
+  cookie answers. `headers` is only what the request carries, fixed when the
+  recipe is made, so never a secret; a bad header or `url` throws then.
+- **A dropped file that is no image** is refused here, as `Unsupported`, before
+  its bytes go anywhere: `accept` filters the picker, not a drop.
+- **For a reader:** the key's label names the group the control is drawn in; the
+  status is one live region, said once per state, while the progress moves under
+  it; a press that takes its button away moves focus on (Cancel and Remove to
+  the file input, Try again to Cancel).
+- **For a stylist:** the root's `data-upload` is the state (`Empty`, `Sending`,
+  `Refused`, `Kept`); `styles.field` styles `ImageSlots` and `styles.drop`
+  `foldkit-mixins-ui`'s `FileDropSlots`; `words` words it. `id` is the drop
+  zone's and its file input's, and where focus is sent, so it is unique on the
+  page and an identifier a selector names (`cover`, not `1cover` or `a.b`).
+- **What it needs:** `foldkit-media`, `@foldkit/ui`, `foldkit-mixins` and
+  `foldkit-mixins-ui` beside the package's own (`./ui` needs `foldkit-mixins`,
+  `foldkit-mixins-ui` and `foldkit-mixins-form`; `./html` `foldkit-mixins-form`).
+- **In `vite dev`,** a Model holding a `File` cannot be kept across a reload, so
+  a send on its way is lost by one.
+
+## Displays
+
+Each recipe's `display` is a `foldkit-crud` Display, for a list or a detail:
+
+```ts
+Entity.annotateMembers({ due: Display.of(due.display) })
+```
+
+`date({ locale: 'de' }).display` reads `make(2026, 3, 5)` as `05.03.2026`; an
+instant reads in its recipe's zone.
+
+## Failure and edge semantics
+
+- **A time the clocks skip is refused.** In `instant` mode, `2026-03-29T01:30` in
+  London names no instant (the clocks go from 01:00 to 02:00), and reads
+  `Enter a date and a time that exists`, the words for any draft that names no
+  time, a partly typed one too. A browser's `new Date` would move it an hour on
+  without saying.
+- **A time the clocks repeat reads as the earlier.** `2026-10-25T01:30` in London
+  happens twice; it submits `00:30Z`, the first.
+- **A year under 100 is that year.** `0050-06-01` is not read as 1950, as
+  `Date.UTC` would.
+- **A fill with a value of the wrong form throws,** naming the form and the key: a
+  `CalendarDate` key given a string, local text in an `instant` key. That is a
+  wiring mistake, so it fails at once rather than showing nothing. So does a
+  recipe made with an option no format can use.
+- **An empty `Schema.String` key submits `''`.** The empty draft is the form's,
+  and a plain string schema accepts it. Give a moment that must be set a schema
+  that refuses it: `Schema.String.check(Schema.isMinLength(1))`.
+- **An image control's draft is not stored mid-send.** A `File` cannot be
+  kept in a stored draft, so `settled` turns `Sending` and `Refused` into
+  `Empty`; a kept image stays.
+- **A late answer is ignored.** Every send has its own attempt number, and an
+  event from a send cancelled or replaced changes nothing.
+
+## Limits
+
+- An email or web address that passes is well-formed, not known to exist: whether
+  it receives mail or answers is the server's to find out.
+- No arithmetic across zones and no zone-aware value type: an instant is text,
+  and its zone is the recipe's.
+- A date is written and read with a four-digit year, 0000 to 9999: a later year
+  is refused, though a date input may take one.
+- `slugify` spells Latin letters only: a title in another script gives an empty
+  slug, which is then written by hand.
+- A browser's own date and time inputs are the default renderers; their look and
+  their picker are the browser's.
+- `image` is a Bundle control, so it takes no `check` and cannot sit in a row of
+  a nested form. There is no `file` recipe: the upload route takes images
+  alone.

package/dist/html.d.mts

@@ -0,0 +1,4 @@
+import { Renderers } from "foldkit-mixins-form";
+/** A renderer for each recipe kind. */
+export declare const renderers: <Message>() => Renderers<Message>;
+//# sourceMappingURL=html.d.mts.map

package/dist/html.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.mts","names":[],"sources":["../src/html.ts"],"mappings":";;qBAqEa,YAAa,cAAY,UAAU"}

package/dist/html.mjs

@@ -0,0 +1,57 @@
+import { t as FieldRecipes } from "./src-CutVZjTd.mjs";
+// src/html.ts
+const { Kinds } = FieldRecipes;
+/** A native input of `type`, holding the draft as typed, with what else the kind asks. */
+const native = (type, extra = () => []) => (context) => {
+	const { state, draft, change, blurred, slots, h } = context;
+	return h.input(slots.text.attrs([
+		...state,
+		h.Type(type),
+		h.Value(String(draft)),
+		h.OnInput(change),
+		h.OnBlur(blurred),
+		...extra(context)
+	]));
+};
+/** What the browser may fill in, and that a keyboard must not capitalize or correct it. */
+const literal = ({ h }, autocomplete) => [
+	h.Attribute("autocomplete", autocomplete),
+	h.Attribute("autocapitalize", "none"),
+	h.Attribute("spellcheck", "false")
+];
+/** The data of a control of `kind`, which the table only hands it. */
+const dataOf = (kind, control) => {
+	if (!kind.is(control)) throw new Error(`a ${control.kind} control under another kind's renderer`);
+	return control.data;
+};
+/**
+* An amount's text input: text, since `"4."` and `"-"` are fine drafts that
+* `type="number"` would refuse to report. Its keypad has a minus only when the
+* amount may be negative (`decimal` has none on iOS), and no point for a whole one.
+*/
+const amount = (of) => native("text", (context) => {
+	const { negative, scale } = of(context.control);
+	return [context.h.InputMode(negative === true ? "text" : scale === 0 ? "numeric" : "decimal"), context.h.Attribute("autocomplete", "off")];
+});
+/** A renderer for each recipe kind. */
+const renderers = () => ({
+	[Kinds.Date.kind]: native("date"),
+	[Kinds.DateTime.kind]: native("datetime-local"),
+	[Kinds.Email.kind]: native("email", (context) => literal(context, dataOf(Kinds.Email, context.control).autocomplete ?? "email")),
+	[Kinds.Url.kind]: native("url", (context) => literal(context, dataOf(Kinds.Url, context.control).autocomplete ?? "url")),
+	[Kinds.Tel.kind]: native("tel", (context) => [context.h.InputMode("tel"), context.h.Attribute("autocomplete", dataOf(Kinds.Tel, context.control).autocomplete ?? "tel")]),
+	[Kinds.Password.kind]: native("password", (context) => literal(context, dataOf(Kinds.Password, context.control).purpose === "new" ? "new-password" : "current-password")),
+	[Kinds.Money.kind]: amount((control) => dataOf(Kinds.Money, control)),
+	[Kinds.Decimal.kind]: amount((control) => dataOf(Kinds.Decimal, control)),
+	[Kinds.Percent.kind]: amount((control) => {
+		const data = dataOf(Kinds.Percent, control);
+		return {
+			negative: data.negative,
+			scale: data.scale ?? 2
+		};
+	}),
+	[Kinds.Slug.kind]: (context) => context.h.div(context.slots.group.attrs(), [context.h.span(context.slots.affix.attrs(), [dataOf(Kinds.Slug, context.control).prefix]), native("text", (inner) => literal(inner, "off"))(context)])
+});
+export { renderers };
+
+//# sourceMappingURL=html.mjs.map

package/dist/html.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.mjs","names":[],"sources":["../src/html.ts"],"sourcesContent":["/**\n * The plain renderers of the recipes' kinds, for `foldkit-mixins-form`'s\n * `FormView.define(form, { renderers })`, beside its own: each a native input\n * the browser already knows how to edit, named by its key so a post without\n * scripts carries it.\n */\nimport type { Control } from 'foldkit-form'\nimport type { Renderer, Renderers, RenderContext } from 'foldkit-mixins-form'\nimport type { Attribute } from 'foldkit/html'\nimport { FieldRecipes } from './index.js'\n\nconst { Kinds } = FieldRecipes\n\n/** A native input of `type`, holding the draft as typed, with what else the kind asks. */\nconst native =\n  <Message>(\n    type: string,\n    extra: (context: RenderContext<Message>) => ReadonlyArray<Attribute<Message>> = () => [],\n  ): Renderer<Message> =>\n  context => {\n    const { state, draft, change, blurred, slots, h } = context\n    return h.input(\n      slots.text.attrs([\n        ...state,\n        h.Type(type),\n        h.Value(String(draft)),\n        h.OnInput(change),\n        h.OnBlur(blurred),\n        ...extra(context),\n      ]),\n    )\n  }\n\n/** What the browser may fill in, and that a keyboard must not capitalize or correct it. */\nconst literal = <Message>(\n  { h }: RenderContext<Message>,\n  autocomplete: string,\n): ReadonlyArray<Attribute<Message>> => [\n  h.Attribute('autocomplete', autocomplete),\n  h.Attribute('autocapitalize', 'none'),\n  h.Attribute('spellcheck', 'false'),\n]\n\n/** The data of a control of `kind`, which the table only hands it. */\nconst dataOf = <Data>(\n  kind: { readonly is: (control: Control) => control is Control<Data> },\n  control: Control,\n): Data => {\n  if (!kind.is(control)) throw new Error(`a ${control.kind} control under another kind's renderer`)\n  return control.data\n}\n\n/**\n * An amount's text input: text, since `\"4.\"` and `\"-\"` are fine drafts that\n * `type=\"number\"` would refuse to report. Its keypad has a minus only when the\n * amount may be negative (`decimal` has none on iOS), and no point for a whole one.\n */\nconst amount = <Message>(\n  of: (control: Control) => { readonly negative?: boolean | undefined; readonly scale: number },\n): Renderer<Message> =>\n  native('text', context => {\n    const { negative, scale } = of(context.control)\n    return [\n      context.h.InputMode(negative === true ? 'text' : scale === 0 ? 'numeric' : 'decimal'),\n      context.h.Attribute('autocomplete', 'off'),\n    ]\n  })\n\n/** A renderer for each recipe kind. */\nexport const renderers = <Message>(): Renderers<Message> => ({\n  [Kinds.Date.kind]: native('date'),\n  [Kinds.DateTime.kind]: native('datetime-local'),\n  [Kinds.Email.kind]: native('email', context =>\n    literal(context, dataOf(Kinds.Email, context.control).autocomplete ?? 'email'),\n  ),\n  [Kinds.Url.kind]: native('url', context =>\n    literal(context, dataOf(Kinds.Url, context.control).autocomplete ?? 'url'),\n  ),\n  [Kinds.Tel.kind]: native('tel', context => [\n    context.h.InputMode('tel'),\n    context.h.Attribute('autocomplete', dataOf(Kinds.Tel, context.control).autocomplete ?? 'tel'),\n  ]),\n  [Kinds.Password.kind]: native('password', context =>\n    literal(\n      context,\n      dataOf(Kinds.Password, context.control).purpose === 'new'\n        ? 'new-password'\n        : 'current-password',\n    ),\n  ),\n  [Kinds.Money.kind]: amount(control => dataOf(Kinds.Money, control)),\n  [Kinds.Decimal.kind]: amount(control => dataOf(Kinds.Decimal, control)),\n  [Kinds.Percent.kind]: amount(control => {\n    const data = dataOf(Kinds.Percent, control)\n    return { negative: data.negative, scale: data.scale ?? 2 }\n  }),\n  // The address before the slug is text beside its input, in the field's affix.\n  [Kinds.Slug.kind]: context =>\n    context.h.div(context.slots.group.attrs(), [\n      context.h.span(context.slots.affix.attrs(), [dataOf(Kinds.Slug, context.control).prefix]),\n      native<Message>('text', inner => literal(inner, 'off'))(context),\n    ]),\n})\n"],"mappings":";;AAWA,MAAM,EAAE,UAAU;;AAGlB,MAAM,UAEF,MACA,cAAsF,CAAC,OAEzF,YAAW;CACT,MAAM,EAAE,OAAO,OAAO,QAAQ,SAAS,OAAO,MAAM;CACpD,OAAO,EAAE,MACP,MAAM,KAAK,MAAM;EACf,GAAG;EACH,EAAE,KAAK,IAAI;EACX,EAAE,MAAM,OAAO,KAAK,CAAC;EACrB,EAAE,QAAQ,MAAM;EAChB,EAAE,OAAO,OAAO;EAChB,GAAG,MAAM,OAAO;CAClB,CAAC,CACH;AACF;;AAGF,MAAM,WACJ,EAAE,KACF,iBACsC;CACtC,EAAE,UAAU,gBAAgB,YAAY;CACxC,EAAE,UAAU,kBAAkB,MAAM;CACpC,EAAE,UAAU,cAAc,OAAO;AACnC;;AAGA,MAAM,UACJ,MACA,YACS;CACT,IAAI,CAAC,KAAK,GAAG,OAAO,GAAG,MAAM,IAAI,MAAM,KAAK,QAAQ,KAAK,uCAAuC;CAChG,OAAO,QAAQ;AACjB;;;;;;AAOA,MAAM,UACJ,OAEA,OAAO,SAAQ,YAAW;CACxB,MAAM,EAAE,UAAU,UAAU,GAAG,QAAQ,OAAO;CAC9C,OAAO,CACL,QAAQ,EAAE,UAAU,aAAa,OAAO,SAAS,UAAU,IAAI,YAAY,SAAS,GACpF,QAAQ,EAAE,UAAU,gBAAgB,KAAK,CAC3C;AACF,CAAC;;AAGH,MAAa,mBAAgD;EAC1D,MAAM,KAAK,OAAO,OAAO,MAAM;EAC/B,MAAM,SAAS,OAAO,OAAO,gBAAgB;EAC7C,MAAM,MAAM,OAAO,OAAO,UAAS,YAClC,QAAQ,SAAS,OAAO,MAAM,OAAO,QAAQ,OAAO,CAAC,CAAC,gBAAgB,OAAO,CAC/E;EACC,MAAM,IAAI,OAAO,OAAO,QAAO,YAC9B,QAAQ,SAAS,OAAO,MAAM,KAAK,QAAQ,OAAO,CAAC,CAAC,gBAAgB,KAAK,CAC3E;EACC,MAAM,IAAI,OAAO,OAAO,QAAO,YAAW,CACzC,QAAQ,EAAE,UAAU,KAAK,GACzB,QAAQ,EAAE,UAAU,gBAAgB,OAAO,MAAM,KAAK,QAAQ,OAAO,CAAC,CAAC,gBAAgB,KAAK,CAC9F,CAAC;EACA,MAAM,SAAS,OAAO,OAAO,aAAY,YACxC,QACE,SACA,OAAO,MAAM,UAAU,QAAQ,OAAO,CAAC,CAAC,YAAY,QAChD,iBACA,kBACN,CACF;EACC,MAAM,MAAM,OAAO,QAAO,YAAW,OAAO,MAAM,OAAO,OAAO,CAAC;EACjE,MAAM,QAAQ,OAAO,QAAO,YAAW,OAAO,MAAM,SAAS,OAAO,CAAC;EACrE,MAAM,QAAQ,OAAO,QAAO,YAAW;EACtC,MAAM,OAAO,OAAO,MAAM,SAAS,OAAO;EAC1C,OAAO;GAAE,UAAU,KAAK;GAAU,OAAO,KAAK,SAAS;EAAE;CAC3D,CAAC;EAEA,MAAM,KAAK,QAAO,YACjB,QAAQ,EAAE,IAAI,QAAQ,MAAM,MAAM,MAAM,GAAG,CACzC,QAAQ,EAAE,KAAK,QAAQ,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,MAAM,QAAQ,OAAO,CAAC,CAAC,MAAM,CAAC,GACxF,OAAgB,SAAQ,UAAS,QAAQ,OAAO,KAAK,CAAC,CAAC,CAAC,OAAO,CACjE,CAAC;AACL"}

package/dist/image.d.mts

@@ -0,0 +1,186 @@
+import { FieldRecipe } from "./index.mjs";
+import { Schema } from "effect";
+import { BundleControl } from "foldkit-form";
+import { HashedAsset } from "foldkit-media";
+import { UploadOptions, UploadRefusal } from "foldkit-media/browser";
+import { Capability, NamedStyle, Slot, Slots } from "foldkit-mixins";
+import { FileDropSlots } from "foldkit-mixins-ui";
+/**
+ * Where the image stands. `Sending` and `Refused` hold the `File` itself, so a
+ * retry sends it again; a stored draft cannot hold one, so `settled` empties them.
+ */
+export declare const ImageUpload: import("foldkit/schema").TaggedUnion<{
+  readonly Empty: {};
+  readonly Sending: {
+    file: Schema.instanceOf<File, File>;
+    attempt: Schema.Number;
+    loaded: Schema.Number;
+    total: Schema.Number;
+  };
+  readonly Refused: {
+    file: Schema.instanceOf<File, File>;
+    reason: Schema.Literals<readonly ["Forbidden", "Unauthenticated", "TooLarge", "Unsupported", "Malformed", "Network", "Unexpected"]>;
+    status: Schema.Number;
+  };
+  readonly Kept: {
+    asset: Schema.refine<HashedAsset, Schema.Struct<{
+      readonly key: Schema.String;
+      readonly width: Schema.Int;
+      readonly height: Schema.Int;
+      readonly alpha: Schema.Boolean;
+      readonly hash: Schema.OptionFromNullOr<Schema.String>;
+      readonly placeholder: Schema.OptionFromNullOr<Schema.TaggedUnion<{
+        readonly Color: Schema.TaggedStruct<"Color", {
+          readonly value: Schema.String;
+        }>;
+        readonly LowRes: Schema.TaggedStruct<"LowRes", {}>;
+        readonly ThumbHash: Schema.TaggedStruct<"ThumbHash", {
+          readonly hash: Schema.String;
+        }>;
+      }>>;
+      readonly focus: Schema.OptionFromOptionalNullOr<Schema.Struct<{
+        readonly x: Schema.Finite;
+        readonly y: Schema.Finite;
+      }>>;
+    }>>;
+  };
+}>;
+export type ImageUpload = typeof ImageUpload.Type;
+export declare const ImageModel: Schema.Struct<{
+  readonly drop: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly isDragOver: Schema.Boolean;
+  }>;
+  readonly upload: import("foldkit/schema").TaggedUnion<{
+    readonly Empty: {};
+    readonly Sending: {
+      file: Schema.instanceOf<File, File>;
+      attempt: Schema.Number;
+      loaded: Schema.Number;
+      total: Schema.Number;
+    };
+    readonly Refused: {
+      file: Schema.instanceOf<File, File>;
+      reason: Schema.Literals<readonly ["Forbidden", "Unauthenticated", "TooLarge", "Unsupported", "Malformed", "Network", "Unexpected"]>;
+      status: Schema.Number;
+    };
+    readonly Kept: {
+      asset: Schema.refine<HashedAsset, Schema.Struct<{
+        readonly key: Schema.String;
+        readonly width: Schema.Int;
+        readonly height: Schema.Int;
+        readonly alpha: Schema.Boolean;
+        readonly hash: Schema.OptionFromNullOr<Schema.String>;
+        readonly placeholder: Schema.OptionFromNullOr<Schema.TaggedUnion<{
+          readonly Color: Schema.TaggedStruct<"Color", {
+            readonly value: Schema.String;
+          }>;
+          readonly LowRes: Schema.TaggedStruct<"LowRes", {}>;
+          readonly ThumbHash: Schema.TaggedStruct<"ThumbHash", {
+            readonly hash: Schema.String;
+          }>;
+        }>>;
+        readonly focus: Schema.OptionFromOptionalNullOr<Schema.Struct<{
+          readonly x: Schema.Finite;
+          readonly y: Schema.Finite;
+        }>>;
+      }>>;
+    };
+  }>;
+  /** How many sends were started: each one's events carry its number, so a cancelled one's are ignored. */
+  readonly attempts: Schema.Number;
+}>;
+export type ImageModel = typeof ImageModel.Type;
+export declare const ImageMessage: import("foldkit/message").MessageUnion<{
+  readonly GotDrop: {
+    message: Schema.Union<readonly [Schema.TaggedStruct<"EnteredDragZone", {}>, Schema.TaggedStruct<"LeftDragZone", {}>, Schema.TaggedStruct<"DroppedFiles", {
+      readonly files: Schema.NonEmptyArray<Schema.instanceOf<File, File>>;
+    }>, Schema.TaggedStruct<"DroppedNonFiles", {}>]>;
+  };
+  readonly Progressed: {
+    attempt: Schema.Number;
+    loaded: Schema.Number;
+    total: Schema.Number;
+  };
+  readonly Uploaded: {
+    attempt: Schema.Number;
+    asset: Schema.refine<HashedAsset, Schema.Struct<{
+      readonly key: Schema.String;
+      readonly width: Schema.Int;
+      readonly height: Schema.Int;
+      readonly alpha: Schema.Boolean;
+      readonly hash: Schema.OptionFromNullOr<Schema.String>;
+      readonly placeholder: Schema.OptionFromNullOr<Schema.TaggedUnion<{
+        readonly Color: Schema.TaggedStruct<"Color", {
+          readonly value: Schema.String;
+        }>;
+        readonly LowRes: Schema.TaggedStruct<"LowRes", {}>;
+        readonly ThumbHash: Schema.TaggedStruct<"ThumbHash", {
+          readonly hash: Schema.String;
+        }>;
+      }>>;
+      readonly focus: Schema.OptionFromOptionalNullOr<Schema.Struct<{
+        readonly x: Schema.Finite;
+        readonly y: Schema.Finite;
+      }>>;
+    }>>;
+  };
+  readonly Failed: {
+    attempt: Schema.Number;
+    reason: Schema.Literals<readonly ["Forbidden", "Unauthenticated", "TooLarge", "Unsupported", "Malformed", "Network", "Unexpected"]>;
+    status: Schema.Number;
+  };
+  readonly Cancelled: {};
+  readonly Retried: {};
+  readonly Removed: {};
+  /** Focus moved on after a press took away the button pressed. */
+  readonly CompletedFocus: {};
+}>;
+export type ImageMessage = typeof ImageMessage.Type;
+/** Every element the control draws, with the drop zone's own two under `FileDropSlots`. */
+export declare const ImageSlots: Slots.Contract<{
+  readonly root: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
+  readonly prompt: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
+  readonly status: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
+  readonly progress: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
+  readonly cancel: Slot.UnnamedSlot<Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
+  readonly retry: Slot.UnnamedSlot<Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
+  readonly remove: Slot.UnnamedSlot<Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
+}>;
+/**
+ * What the control says. `{name}`, `{width}` and `{height}` are filled. Each is
+ * said once, in a live region: the progress shows how far a send has gone.
+ */
+export interface ImageWords {
+  readonly prompt: string;
+  readonly sending: string;
+  readonly kept: string;
+  readonly cancel: string;
+  readonly retry: string;
+  readonly remove: string;
+  /** Why a send was refused, by the route's reason. */
+  readonly refused: { readonly [R in UploadRefusal]: string; };
+}
+export declare const imageWords: ImageWords;
+export interface ImageOptions extends UploadOptions {
+  /**
+   * The drop zone's `id`, which its file input takes: unique on the page, so
+   * two image keys never share one.
+   */
+  readonly id: string;
+  readonly words?: Partial<Omit<ImageWords, 'refused'>> & {
+    readonly refused?: Partial<ImageWords['refused']> | undefined;
+  };
+  readonly styles?: {
+    readonly field?: NamedStyle<typeof ImageSlots> | undefined;
+    readonly drop?: NamedStyle<typeof FileDropSlots> | undefined;
+  };
+}
+/**
+ * An image key: its value is the `HashedAsset` the upload route kept. The
+ * Bundle uploads a file once it is chosen, through `upload` with `url` and
+ * `headers`, so who may upload is still the route's `UploadPolicy`. Like every
+ * Bundle control it has no `check`, and a row of a nested form cannot hold it.
+ */
+export declare const image: (options: ImageOptions) => FieldRecipe<BundleControl<ImageModel, ImageMessage, HashedAsset>>;
+//# sourceMappingURL=image.d.mts.map

package/dist/image.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.mts","names":[],"sources":["../src/image.ts"],"mappings":";;;;;;;;;;;qBA+Ca,sCAAW;;;IAGpB,MAAI,OAAA,WAAA,MAAA;IACJ,SAAO,OAAA;IACP,QAAM,OAAA;IACN,OAAK,OAAA;;;IAEI,MAAI,OAAA,WAAA,MAAA;IAAc,QAAM,OAAA;IAAiB,QAAM,OAAA;;;IAClD,OAAK,OAAA,OAAA,aAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;YAEH,qBAAqB,YAAY;qBAEhC,YAAU,OAAA;;;;;;;;MAVnB,MAAI,OAAA,WAAA,MAAA;MACJ,SAAO,OAAA;MACP,QAAM,OAAA;MACN,OAAK,OAAA;;;MAEI,MAAI,OAAA,WAAA,MAAA;MAAc,QAAM,OAAA;MAAiB,QAAM,OAAA;;;MAClD,OAAK,OAAA,OAAA,aAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;YAUH,oBAAoB,WAAW;qBAY9B,wCAAY;;IACZ,SAAO,OAAA,gBAAA,OAAA,qCAAA,OAAA,kCAAA,OAAA;;;;;IACJ,SAAO,OAAA;IAAiB,QAAM,OAAA;IAAiB,OAAK,OAAA;;;IACtD,SAAO,OAAA;IAAiB,OAAK,OAAA,OAAA,aAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;IAC/B,SAAO,OAAA;IAAiB,QAAM,OAAA;IAAiB,QAAM,OAAA;;;;;;;;YAOrD,sBAAsB,aAAa;;qBAGlC,YAAU,MAAA;;;;;;;;;;;;;iBAcN;WACN;WACA;WACA;WACA;WACA;WACA;;WAEA,qBAAqB,KAAK;;qBAGxB,YAAY;iBAkBR,qBAAqB;;;;;WAK3B;WACA,QAAQ,QAAQ,KAAK;aACnB,UAAU,QAAQ;;WAEpB;aACE,QAAQ,kBAAkB;aAC1B,OAAO,kBAAkB;;;;;;;;;qBAuOzB,QAAK,SACP,iBACR,YAAY,cAAc,YAAY,cAAc"}