@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/components/paste-button.md

@@ -0,0 +1,48 @@
+# PasteButton
+
+Reads plain text with the async Clipboard API inside the user's press. `onPaste` receives a string, which can be empty. `onError` is required and receives permission, unsupported-platform or read failures.
+
+WebKit may show its own Paste confirmation before returning text. Dismissal and denial cannot be reliably distinguished. The component never reads clipboard contents during render or probes whether a paste is available. It cannot pre-disable itself based on clipboard contents.
+
+This version supports plain text only, not arbitrary transferable objects or clipboard images. No hidden editable field, synthetic paste, permission polling or clipboard cache bypasses WebKit's prompt.
+
+## Example
+
+Copy some text, then press Paste and approve WebKit’s paste prompt if shown.
+
+<!-- example: paste-button open -->
+
+```tsx
+import { useState } from 'react'
+import { PasteButton, LabeledContent, List, Screen, Section } from '@satinhq/kit'
+
+function Example() {
+  const [message, setMessage] = useState('No text pasted')
+
+  return (
+    <Screen>
+      <List id="example">
+        <Section>
+          <PasteButton
+            onPaste={text => setMessage(text || 'Clipboard contains no text')}
+            onError={error => setMessage(error.message)}
+          />
+          <LabeledContent label="Result" value={message} />
+        </Section>
+      </List>
+    </Screen>
+  )
+}
+```
+
+## Action lifetime
+
+Repeated presses are disabled while the browser operation is pending. An observed disabled, covered-screen or mount change suppresses its result. Key the control by draft identity when replacing a draft. This does not dismiss a system sheet or revoke work the platform has already accepted.
+
+## Platform limits and evidence
+
+Use an HTTPS installed app. Browser capability and permission policy still apply. Embedded docs previews may block these APIs; open the example in its own page when needed. The framework does not replace a system prompt with a simulated picker, share sheet or paste menu.
+
+Software regression coverage is separate from installed-device acceptance. Installed selection, cancellation, focus return and touch feedback for this revision are pending; no native visual or motion parity is claimed.
+
+Platform reference: [WebKit async clipboard](https://webkit.org/blog/10855/async-clipboard-api/).

package/dist/docs/components/photos-picker.md

@@ -0,0 +1,53 @@
+# PhotosPicker
+
+Selects one photo or video using a real file input. The browser chooses the source menu and picker UI. This does not embed Apple's PhotosUI framework.
+
+`selection` is the accepted `File | null`; `onSelectionChange` receives a new File. `matching` accepts `images`, `videos`, or `imagesAndVideos`. `capture="user"` or `"environment"` supplies a browser camera preference, not a camera guarantee. No photo-library permission probe runs.
+
+The browser may offer Photo Library, camera or Files. The control does not expose PhotosPickerItem identifiers, ordered multi-selection, persistent library access, or native filter objects. File decoding, object URLs, storage and validation belong to the app.
+
+## Example
+
+Choose a photo to read its file name. Cancel keeps the current selection.
+
+<!-- example: photos-picker open -->
+
+```tsx
+import { useState } from 'react'
+import { PhotosPicker, LabeledContent, List, Screen, Section } from '@satinhq/kit'
+
+function Example() {
+  const [photo, setPhoto] = useState<File | null>(null)
+  const [message, setMessage] = useState('No photo selected')
+
+  return (
+    <Screen>
+      <List id="example">
+        <Section>
+          <PhotosPicker
+            selection={photo}
+            onSelectionChange={file => {
+              setPhoto(file)
+              setMessage(file.name)
+            }}
+            onError={error => setMessage(error.message)}
+          />
+          <LabeledContent label="Result" value={message} />
+        </Section>
+      </List>
+    </Screen>
+  )
+}
+```
+
+## Selection lifetime
+
+Cancel leaves the accepted selection unchanged. The input resets after delivery, allowing the same file to be selected again. Observed disabled, covered-screen, selection or mount changes invalidate an outstanding result. Key the picker by draft identity when replacing a draft whose selection has not changed. Browser events carry no chooser session ID, so overlapping choosers cannot be attributed exactly. Already-started decoding or storage is still app-owned.
+
+## Platform limits and evidence
+
+Use an HTTPS installed app. Browser capability and permission policy still apply. Embedded docs previews may block these APIs; open the example in its own page when needed. The framework does not replace a system prompt with a simulated picker, share sheet or paste menu.
+
+Software regression coverage is separate from installed-device acceptance. Installed selection, cancellation, focus return and touch feedback for this revision are pending; no native visual or motion parity is claimed.
+
+Platform reference: [HTML file upload state](https://html.spec.whatwg.org/multipage/input.html#file-upload-state-(type=file)).

package/dist/docs/components/share-link.md

@@ -0,0 +1,58 @@
+# ShareLink
+
+Opens the platform share sheet using Web Share. Pass prepared `item` data containing `title`, `text`, `url`, or `files`. For files, prepare real File objects before the press; the framework checks `navigator.canShare({ files })` and never silently drops unsupported attachments.
+
+`onCompletion` reports the browser's completed handoff, not delivery to a recipient. `onError` is required. An AbortError can mean dismissal or no suitable target; it is not proof of a user cancellation. Unsupported sharing or files report NotSupportedError. Other browser errors retain their names.
+
+The operating system chooses share targets and previews. Custom transferable objects, preview models and activity lists are unavailable. Keep `item` stable while sharing; changing its identity invalidates delivery to the old owner.
+
+## Example
+
+Press Share Note to open the system share sheet.
+
+<!-- example: share-link open -->
+
+```tsx
+import { useState } from 'react'
+import { ShareLink, LabeledContent, List, Screen, Section } from '@satinhq/kit'
+
+function Example() {
+  const [message, setMessage] = useState('Ready to share')
+  const [item] = useState(() => ({ text: 'A note shared from my app.' }))
+
+  return (
+    <Screen>
+      <List id="example">
+        <Section>
+          <ShareLink
+            item={item}
+            onCompletion={() => setMessage('Share handoff complete')}
+            onError={error =>
+              setMessage(
+                error.name === 'AbortError'
+                  ? 'Share dismissed or no target available'
+                  : error.message,
+              )
+            }
+          >
+            Share Note
+          </ShareLink>
+          <LabeledContent label="Result" value={message} />
+        </Section>
+      </List>
+    </Screen>
+  )
+}
+```
+
+## Action lifetime
+
+Repeated presses are disabled while the browser operation is pending. An observed disabled, covered-screen or mount change suppresses its result. Key the control by draft identity when replacing a draft. This does not dismiss a system sheet or revoke work the platform has already accepted.
+
+## Platform limits and evidence
+
+Use an HTTPS installed app. Browser capability and permission policy still apply. Embedded docs previews may block these APIs; open the example in its own page when needed. The framework does not replace a system prompt with a simulated picker, share sheet or paste menu.
+
+Software regression coverage is separate from installed-device acceptance. Installed selection, cancellation, focus return and touch feedback for this revision are pending; no native visual or motion parity is claimed.
+
+Platform reference: [Web Share specification](https://www.w3.org/TR/web-share/).

package/dist/docs/content.md

@@ -0,0 +1,159 @@
+# Content
+
+Prefer Satin's optional content components for new app content. The framework owns their defaults. Plain React and semantic HTML remain supported; there is no adoption lint rule or warning. Keep framework chrome and geometry in Screen, List, Form and ScrollView.
+
+Text rendering has differences from the iOS reference. See [Known issues](https://github.com/satinhq/satin/blob/main/docs/known-issues.md#working-on).
+
+## Text
+
+```tsx
+import { Text } from '@satinhq/kit'
+
+<Text font="headline" foregroundStyle="secondary" lineLimit={2}>
+  A familiar heading
+</Text>
+```
+
+`font` accepts largeTitle, title, title2, title3, headline, subheadline, body, callout, footnote, caption and caption2. Typography uses a shared iOS 27 default-size metric table, also consumed by Settings large-title tokens. Supported WebKit semantic styles retain system tracking; largeTitle and callout use explicit system-font sizes because their WebKit keywords are unsupported. Single-line glyph height is rounded to the device pixel. `fontWeight` accepts ultraLight through black. Serif design is deferred under the current system-font-only product policy. `fontDesign` selects the platform's default, rounded or monospaced system design. Nested Text inherits the enclosing font and foreground unless overridden. Text uses a span; place it in a semantic heading when a heading is intended. Text does not change the existing Selectable policy.
+
+`multilineTextAlignment` is leading, center or trailing. `lineLimit` is a positive integer. `truncationMode` currently supports tail; head and middle truncation are deferred. Multiline limiting uses WebKit line clamping and ends in an ellipsis. `lineLimit` does not reserve empty lines.
+
+## VStack
+
+```tsx
+import { VStack, Text } from '@satinhq/kit'
+
+<VStack alignment="leading" spacing={12}>
+  <Text font="headline">Inbox</Text>
+  <Text foregroundStyle="secondary">No new messages</Text>
+</VStack>
+```
+
+Alignment defaults to center. An explicit spacing, including zero, is exact. Omitted vertical spacing uses the measured iOS 27 direct-child gaps: Text/Text and automatic Button/Button 2 points, Text/SymbolImage 0. Other pairs fall back to 8 points; wrappers and custom controls do not yet propagate child spacing preferences. Use explicit spacing for those cases.
+
+## HStack
+
+```tsx
+import { HStack, Text } from '@satinhq/kit'
+
+<HStack alignment="firstTextBaseline" spacing={8}>
+  <Text font="title">42</Text>
+  <Text>items</Text>
+</HStack>
+```
+
+Alignment accepts top, center, bottom, firstTextBaseline or lastTextBaseline. Defaults center. Leading/trailing directions follow document direction. Compression uses CSS flex rules; proposal-based ordering and a layoutPriority contract are not provided.
+
+## ZStack
+
+```tsx
+import { ZStack, Text } from '@satinhq/kit'
+
+<ZStack alignment="bottomTrailing">
+  <div style={{ width: 120, height: 80, background: '#ddd' }} />
+  <Text padding={8}>3</Text>
+</ZStack>
+```
+
+Children share a CSS grid cell. The default alignment is center and later children paint above earlier children. Content remains in source order for accessibility.
+
+## Spacer
+
+```tsx
+import { HStack, Spacer, Text } from '@satinhq/kit'
+
+<HStack spacing={0} frame={{ maxWidth: 'infinity' }}>
+  <Text>Title</Text>
+  <Spacer minLength={12} />
+  <Text>Value</Text>
+</HStack>
+```
+
+Spacer grows along its direct stack parent's axis. `minLength` defaults to 8 points; zero is supported. Wrapping Spacer in arbitrary DOM changes its direct layout parent. Give the parent a bounded frame when remaining space should be consumed.
+
+## Divider
+
+```tsx
+import { VStack, Divider, Text } from '@satinhq/kit'
+
+<VStack alignment="leading" spacing={8}>
+  <Text>Above</Text>
+  <Divider />
+  <Text>Below</Text>
+</VStack>
+```
+
+Divider is decorative and uses the framework device-pixel token. It is vertical inside a direct HStack and horizontal otherwise. Its semantic separator colors follow appearance.
+
+## LazyVStack
+
+```tsx
+import { Text } from '@satinhq/kit'
+import { LazyVStack } from '@satinhq/kit'
+
+<LazyVStack alignment="leading" spacing={8}>
+  {['One', 'Two'].map(item => <Text key={item}>{item}</Text>)}
+</LazyVStack>
+```
+
+## LazyHStack
+
+```tsx
+import { Text } from '@satinhq/kit'
+import { LazyHStack } from '@satinhq/kit'
+
+<LazyHStack spacing={12}>
+  {['One', 'Two'].map(item => <Text key={item}>{item}</Text>)}
+</LazyHStack>
+```
+
+Both lazy stacks currently retain all children. They do not create a scroll surface. Use ScrollView for scrolling. They do not virtualize rows.
+
+## GridItem and LazyVGrid
+
+```tsx
+import { Text } from '@satinhq/kit'
+import { GridItem, LazyVGrid } from '@satinhq/kit'
+
+const columns = [GridItem.fixed(80), GridItem.flexible({ minimum: 40 })]
+<LazyVGrid columns={columns} spacing={8}>
+  <Text>Label</Text>
+  <Text>Value</Text>
+</LazyVGrid>
+```
+
+`GridItem.fixed({ size: 80, spacing: 12, alignment: 'leading' })`, `GridItem.flexible({ minimum: 40 })` and `GridItem.adaptive({ minimum: 150, spacing: 16 })` create validated, frozen tracks. The numeric `fixed(80)` form remains supported. Track spacing follows its column or row; the last explicit track has no trailing gap. Flexible tracks default to a 10-point minimum. Maximum bounds are optional. One adaptive descriptor repeats to fit the available space. Mixed adaptive descriptors remain unsupported.
+
+## LazyHGrid
+
+```tsx
+import { Text } from '@satinhq/kit'
+import { GridItem, LazyHGrid } from '@satinhq/kit'
+
+<LazyHGrid rows={[GridItem.fixed(44), GridItem.fixed(44)]} spacing={8}>
+  <Text>Top</Text>
+  <Text>Bottom</Text>
+</LazyHGrid>
+```
+
+All five layout APIs are stable exports. They render eagerly with no viewport virtualization; use List for long data. `LazyVGrid.spacing` is row spacing and `LazyHGrid.spacing` is column spacing. Track spacing and line spacing each default to 8 points independently. Grid alignment is leading/center/trailing for vertical grids and top/center/bottom for horizontal grids. Track alignment places intrinsic content inside its cell; a content `frame={{ maxWidth: 'infinity' }}` consumes the full cell width. Grid/GridRow and pinned headers remain unsupported.
+
+## Shared props
+
+```tsx
+import { Text } from '@satinhq/kit'
+
+<Text
+  padding
+  frame={{ maxWidth: 'infinity', alignment: 'leading' }}
+  background="#eee"
+>
+  Full-width label
+</Text>
+```
+
+`padding` means the default 16-point inset. A number applies to every edge; an object accepts top, bottom, leading, trailing, horizontal and vertical, with explicit edges taking precedence. `frame` accepts width, height, minimum and maximum bounds; maximum width/height may be `infinity`. Percentage height needs a bounded parent, as in CSS. `background` accepts a CSS background value. Shared foregroundStyle accepts primary, secondary, tertiary or a CSS color. An explicit `style` overrides generated CSS.
+
+Padding applies to the content, frame wraps it with independent horizontal and vertical alignment, and background covers that frame. A wrapper is created only when a frame is requested. Arbitrary modifier ordering and proposal-priority layout remain deferred. The API is opt-in.
+
+LazyVStack/LazyVGrid do not yet support `pinnedViews`. Section outside List still has list styling; use ordinary semantic headings and grouping for now. Neutral Section and pinned headers are unsupported.

package/dist/docs/controls.md

@@ -0,0 +1,151 @@
+# Controls
+
+DatePicker and ColorPicker draw the native rows and open the system pickers: the same UIKit
+calendar, time wheel and colour picker supplied by WebKit.
+
+```tsx
+import { ColorPicker, DatePicker, Form, ProgressView, Section } from '@satinhq/kit'
+import { useState } from 'react'
+
+function Settings() {
+  const [due, setDue] = useState(new Date())
+  const [tint, setTint] = useState('#0088ff')
+  return (
+    <Form id="settings">
+      <Section header="Download">
+        <ProgressView label="Downloading" value={40} total={100} />
+        <ProgressView label="Waiting" />
+      </Section>
+      <Section header="Reminder">
+        <DatePicker label="Due" selection={due} onSelectionChange={setDue} />
+      </Section>
+      <Section header="Appearance">
+        <ColorPicker label="Tint" selection={tint} onSelectionChange={setTint}
+          supportsOpacity={false} />
+      </Section>
+    </Form>
+  )
+}
+```
+
+ProgressView omits `value` for an indeterminate spinner. Determinate values clamp to `0...total`;
+`total` defaults to 1 and must be finite and positive. Labels can be React content; use
+`aria-label` for a label without meaningful accessible text. Tint inherits the control environment.
+The spinner uses the refresh indicator's eight segments and animation.
+
+## DatePicker
+
+`DatePicker` uses the compact style by default in a Form: grey capsules
+with the date and time. Tapping one opens the system date or time picker; its value turns the
+tint colour while the picker is open. Changes arrive as the user picks.
+
+The selection is a `Date` or a civil string, and the callback returns the same kind:
+
+| Selection | `displayedComponents` | Meaning |
+| --- | --- | --- |
+| `Date` | any | A moment in time. Edits change its calendar fields in the device's time zone. |
+| `'2026-10-14'` | `['date']` | A day. It is the same day in every time zone. |
+| `'09:41'` | `['hourAndMinute']` | A time of day. |
+| `'2026-10-14T09:41'` | both (the default) | A day and time with no time zone ("floating"). |
+
+Use a civil string for things like due dates and birthdays, which must not move when the user
+travels; use a `Date` for a moment such as a meeting start. Never build a civil date with
+`new Date('2026-10-14')`: JavaScript reads that as UTC midnight, the previous day in the
+Americas.
+
+```tsx
+const [due, setDue] = useState('2026-10-14')
+<DatePicker label="Due" selection={due} onSelectionChange={setDue} displayedComponents={['date']} />
+```
+
+`in` sets the allowed range: `in={{ lowerBound: start, upperBound: end }}`, either bound optional,
+using the same kind of value as the selection. A choice outside the range is clamped to the
+nearest bound, as UIDatePicker does.
+The capsule text uses the user's locale ("Oct 14, 2026", "9:41 AM" in US English).
+
+Differences from native, all inside WebKit's system picker: it shows Reset and Done buttons
+(Reset leaves the selection unchanged; a DatePicker always has a value); it sits in the middle of
+the screen rather than under the capsule; and it doesn't grey out days outside `in`, so a day
+past a bound is selectable there and then clamped. `graphical` and `wheel` styles are not
+available yet.
+
+## ColorPicker
+
+`ColorPicker` is a row with the native colour well. Tapping the well opens the system colour
+picker: grid, spectrum and sliders, the eyedropper, and saved colours. With `supportsOpacity`
+(the default) it also shows the opacity slider.
+
+The selection is sRGB `#RRGGBB` or `#RRGGBBAA`. The callback returns eight digits with
+`supportsOpacity` and six without. A Display P3 colour chosen in the spectrum is converted to
+sRGB. The system picker is titled "Colors" instead of the row's label.
+
+Both controls take their disabled state from the control environment, and render an inert row
+(with a console error) if their selection is malformed, so bad stored data doesn't crash a screen.
+
+Controls adopt List/Form rows automatically. Inside an explicit ListRow they reuse its cell;
+they do not create another row or another activation owner.
+
+```tsx
+import { List, Section, Text } from '@satinhq/kit'
+
+<List id="compact-settings" listSectionSpacing="compact">
+  <Section><Text>First</Text></Section>
+  <Section header="Options"><Text>Second</Text></Section>
+</List>
+```
+
+Compact section spacing follows the measured inset-grouped native reference allocation: 12 pt between
+headerless sections, reduced allocation before a following header, and preserved footer-plus-header
+space. Numeric spacing retains its existing explicit point-value contract. DisclosureGroup is
+not available; use visible sections.
+
+See [current limitations](limitations.md).
+
+## Editing a list
+
+`ForEach` identifies the rows; `onDelete` gives each row
+swipe-to-delete and, in edit mode, the red delete control; `onMove` adds the reorder handle.
+An `EditButton` in the screen's toolbar toggles edit mode for every list on that screen.
+
+```tsx
+import { EditButton, ForEach, List, ListRow, Screen, ToolbarItem, moving, removing } from '@satinhq/kit'
+
+const [todos, setTodos] = useState(initialTodos)
+const [selection, setSelection] = useState(new Set<string>())
+
+<Screen toolbar={<ToolbarItem placement="topBarTrailing"><EditButton /></ToolbarItem>}>
+  <List id="todos" selection={selection} onSelectionChange={setSelection}>
+    <ForEach
+      data={todos}
+      onDelete={offsets => setTodos(todos => removing(todos, offsets))}
+      onMove={(from, to) => setTodos(todos => moving(todos, { fromOffsets: from, toOffset: to }))}
+    >
+      {todo => <ListRow>{todo.title}</ListRow>}
+    </ForEach>
+  </List>
+</Screen>
+```
+
+- **Offsets** are positions in `data` before the change: dragging the first of
+  three rows below the second reports `toOffset` 2. `moving` and `removing` apply them and return
+  a new array, so store the result.
+- **Selection:** pass an id (or `null`) to select one row, or a `Set` to select many. A `Set`
+  shows selection circles while editing, and taps toggle them. Outside edit mode a tap replaces
+  the selection. Entering edit mode clears it.
+- **Per row:** `ListRow` takes `moveDisabled`, `deleteDisabled` and `selectionDisabled`. A row's
+  own trailing `swipeActions` replace swipe-to-delete.
+- **Your own toolbar:** `useEditMode()` returns `[editMode, setEditMode]` for the same screen, so a
+  bottom bar can follow edit mode.
+
+
+## ProgressView styles
+
+```tsx
+<ProgressView value={0.4} progressViewStyle="circular" />
+<ProgressView label="Loading" progressViewStyle="linear" />
+```
+
+`progressViewStyle` accepts `automatic`, `linear` and `circular`. Automatic selects the
+value-dependent default. On iOS the explicit circular style draws an activity indicator even
+with a value; an indeterminate linear style draws an empty track. These static cases follow
+native Simulator measurements. The existing track and spinner remain their only renderers.