create-satin 0.1.0-beta.3 → 0.1.0-beta.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/template/AGENTS.md +83 -81
- package/template/GETTING-STARTED.md +5 -2
- package/template/README.md +2 -2
- package/template/package.json +1 -1
- package/template/src/main.tsx +0 -1
package/package.json
CHANGED
package/template/AGENTS.md
CHANGED
|
@@ -24,8 +24,8 @@ The generated family table below uses that same reviewed concept metadata. It is
|
|
|
24
24
|
| Entry point | Supported use and limits | Exact reference / example |
|
|
25
25
|
| --- | --- | --- |
|
|
26
26
|
| `@satinhq/kit` | App components, state and hooks. Mount once through `runApp`; let its root own navigation, media, keyboard, restoration and updates. App callbacks own domain validation, writes and user-visible errors. | [Root declarations](node_modules/@satinhq/kit/dist/index.d.ts), family table below, README examples. |
|
|
27
|
-
|
|
|
28
|
-
| `@satinhq/kit/vite` | Use `satinApp` with the same `defineApp` definition used by the runtime. It generates the app, install/unsupported documents, manifest and worker. Lower-level shell and fixture tools (`satinAppShell`, `satinAppFixtures`, `defineAppFixture`) are available from the Node-only `@satinhq/kit/internal/vite` entry, not the stable Vite entry or a second app root. Do not register another worker. | [Build declarations](node_modules/@satinhq/kit/dist/sw/vite.d.ts), scaffold `vite.config.ts`. |
|
|
27
|
+
| Framework styles | Included by `satinApp()` before app CSS. Keep system fonts and framework geometry; do not add a global reset or overwrite control internals. | [Stylesheet](node_modules/@satinhq/kit/dist/styles.css), scaffold `vite.config.ts`. |
|
|
28
|
+
| `@satinhq/kit/vite` | Use `satinApp` with the same `defineApp` definition used by the runtime. It includes framework CSS before app CSS and generates the app, install/unsupported documents, manifest and worker. Lower-level shell and fixture tools (`satinAppShell`, `satinAppFixtures`, `defineAppFixture`) are available from the Node-only `@satinhq/kit/internal/vite` entry, not the stable Vite entry or a second app root. Do not register another worker. | [Build declarations](node_modules/@satinhq/kit/dist/sw/vite.d.ts), scaffold `vite.config.ts`. |
|
|
29
29
|
| `@satinhq/kit/install` | Custom install pages only. `readInstallContext` / `useInstallContext` read the generated page context; they throw outside that page. `InstallSteps` and `InstallTip` supply framework instructions. `copyInstallLink` reports clipboard success or the URL to offer manually. `standalone` does not tell a Safari tab whether a clip already exists. | [Install declarations](node_modules/@satinhq/kit/dist/install.d.ts), example below. |
|
|
30
30
|
| `@satinhq/kit/server` | Node-only `serveStaticFile` streams static GET/HEAD responses and single byte ranges within a root directory. It supplies no authentication, upload handling, compression or production cache policy. Keep it out of the browser bundle. A successful media response does not prove device playback. | [Server declaration](node_modules/@satinhq/kit/dist/server.d.ts), example below. |
|
|
31
31
|
| `@satinhq/kit/testing` | Test-only `assertNavigation` checks the active route in a DOM container. `sendTestNotification` requests a relay token at call time and returns the accepted count. Neither proves physical touches, notification display or delivery. | [Testing declarations](node_modules/@satinhq/kit/dist/testing.d.ts). Example: `assertNavigation(container, 'detail')` after your test navigation; `await sendTestNotification({ url, token })` for an explicitly authorized relay test. |
|
|
@@ -75,85 +75,87 @@ Generated from the same reviewed metadata as the shipped Satin API reference. Li
|
|
|
75
75
|
|
|
76
76
|
| Satin exports and declarations | Behavior and ownership | Limits |
|
|
77
77
|
| --- | --- | --- |
|
|
78
|
-
| [`Overlay`](node_modules/@satinhq/kit/dist/safe-area/Overlay.d.ts) | Layer content over a view without changing its frame.
|
|
79
|
-
| [`ProgressView`](node_modules/@satinhq/kit/dist/controls/ProgressView.d.ts) |
|
|
80
|
-
| [`GeometryReader`](node_modules/@satinhq/kit/dist/content/layout.d.ts) | Report
|
|
81
|
-
| [`ViewThatFits`](node_modules/@satinhq/kit/dist/content/layout.d.ts) |
|
|
82
|
-
| [`useScaledMetric`](node_modules/@satinhq/kit/dist/content/scaledMetric.d.ts) | Scale a
|
|
83
|
-
| [`Text`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`VStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`HStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`ZStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`Spacer`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`Divider`](node_modules/@satinhq/kit/dist/content/content.d.ts) |
|
|
84
|
-
| [`LazyVStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`LazyHStack`](node_modules/@satinhq/kit/dist/content/content.d.ts)
|
|
85
|
-
| [`
|
|
86
|
-
| [`
|
|
87
|
-
| [`
|
|
88
|
-
| [`
|
|
89
|
-
| [`
|
|
90
|
-
| [`
|
|
91
|
-
| [`
|
|
92
|
-
| [`
|
|
93
|
-
| [`
|
|
94
|
-
| [`
|
|
95
|
-
| [`List`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`Form`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`
|
|
96
|
-
| [`
|
|
97
|
-
| [`
|
|
98
|
-
| [`
|
|
99
|
-
| [`
|
|
100
|
-
| [`
|
|
101
|
-
| [`
|
|
102
|
-
| [`
|
|
103
|
-
| [`
|
|
104
|
-
| [`
|
|
105
|
-
| [`
|
|
106
|
-
| [`
|
|
107
|
-
| [`
|
|
108
|
-
| [`
|
|
109
|
-
| [`
|
|
110
|
-
| [`
|
|
111
|
-
| [`
|
|
112
|
-
| [`
|
|
113
|
-
| [`
|
|
114
|
-
| [`
|
|
115
|
-
| [`
|
|
116
|
-
| [`
|
|
117
|
-
| [`
|
|
118
|
-
| [`
|
|
119
|
-
| [`
|
|
120
|
-
| [`
|
|
121
|
-
| [`
|
|
122
|
-
| [`
|
|
123
|
-
| [`
|
|
124
|
-
| [`
|
|
125
|
-
| [`
|
|
126
|
-
| [`
|
|
127
|
-
| [`
|
|
128
|
-
| [`
|
|
129
|
-
| [`
|
|
130
|
-
| [`
|
|
131
|
-
| [`
|
|
132
|
-
| [`
|
|
133
|
-
| [`
|
|
134
|
-
| [`
|
|
135
|
-
| [`
|
|
136
|
-
| [`
|
|
137
|
-
| [`
|
|
138
|
-
| [`
|
|
139
|
-
| [`
|
|
140
|
-
| [`
|
|
141
|
-
| [`
|
|
142
|
-
| [`
|
|
143
|
-
| [`
|
|
144
|
-
| [`
|
|
145
|
-
| [`
|
|
146
|
-
| [`
|
|
147
|
-
| [`
|
|
148
|
-
| [`
|
|
149
|
-
| [`
|
|
150
|
-
| [`
|
|
151
|
-
| [`
|
|
152
|
-
| [`
|
|
153
|
-
| [`
|
|
154
|
-
| [`
|
|
155
|
-
| [`
|
|
156
|
-
| [`
|
|
78
|
+
| [`Overlay`](node_modules/@satinhq/kit/dist/safe-area/Overlay.d.ts) | Layer content over a view without changing its frame. Inside a SafeAreaInset the overlay keeps to the reduced safe area and moves with the keyboard, like the composer. | Only views can be overlaid; there is no shape or style overlay. |
|
|
79
|
+
| [`ProgressView`](node_modules/@satinhq/kit/dist/controls/ProgressView.d.ts) | Show an indeterminate spinner or a linear bar for a value, with an optional label, inherited tint and accessible progress values. progressViewStyle chooses linear, circular or automatic. | Circular progress always spins; it does not show a value. Indeterminate linear progress draws an empty track. See controls.md. |
|
|
80
|
+
| [`GeometryReader`](node_modules/@satinhq/kit/dist/content/layout.d.ts) | Report the space a reader is given to a render function; frame() reads its position in the viewport or relative to an element. | Inside a scroll view, give it a definite height. The proxy reports no safe-area insets. |
|
|
81
|
+
| [`ViewThatFits`](node_modules/@satinhq/kit/dist/content/layout.d.ts) | Show the first child whose natural size fits the constrained axes, or the last child when none fits. | Give it a definite height when it checks the vertical axis. Every child stays mounted: hidden children are inert and pause Satin tasks and activity indicators, but their own effects keep running. |
|
|
82
|
+
| [`useScaledMetric`](node_modules/@satinhq/kit/dist/content/scaledMetric.d.ts) | Scale a number with the user's text size, relative to a text style. | largeTitle and callout scale by fixed fallbacks, because WebKit has no system font keyword for them. |
|
|
83
|
+
| [`Text`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`VStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`HStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`ZStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`Spacer`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`Divider`](node_modules/@satinhq/kit/dist/content/content.d.ts) | Lay out content with system text styles, semantic colours, padding and frame props. Plain React and HTML still work. | Default spacing and frame differences are listed in content.md. Props apply in a fixed order, not the order you write them. |
|
|
84
|
+
| [`LazyVStack`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`LazyHStack`](node_modules/@satinhq/kit/dist/content/content.d.ts) | Lay out a stack whose children keep their state. Use List for long data. | Every child renders at once; there is no virtualization. |
|
|
85
|
+
| [`LazyVGrid`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`LazyHGrid`](node_modules/@satinhq/kit/dist/content/content.d.ts), [`GridItem`](node_modules/@satinhq/kit/dist/content/content.d.ts) | Lay out grids with per-track spacing and alignment. Use List for long data. | Every child renders at once; there is no virtualization. An adaptive track must be the only track, and there is no Grid or GridRow. |
|
|
86
|
+
| [`useTask`](node_modules/@satinhq/kit/dist/tasks/useTask.d.ts) | Run cancellable work while a screen shows. A change of id, or a call to the returned runner, replaces the current run. Pass the AbortSignal to fetch and publish through commit. | Cancellation is cooperative: state set outside commit cannot be stopped. The work runs in the foreground only; it is not a Web Worker or a background scheduler. |
|
|
87
|
+
| [`List`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`ScrollView`](node_modules/@satinhq/kit/dist/public/scroll.d.ts) | Pass refreshable to a vertical List or ScrollView to add pull to refresh. The indicator stays until the returned promise settles. | The refresh indicator holds a 60 pt inset while the action runs. |
|
|
88
|
+
| [`defineApp`](node_modules/@satinhq/kit/dist/public/definition.d.ts), [`runApp`](node_modules/@satinhq/kit/dist/public/runtime.d.ts), [`defineNavigation`](node_modules/@satinhq/kit/dist/public/structure.d.ts) | Declare install metadata and primary navigation, then mount the app once with runApp. | One app root per page, for iPhone and iPad WebKit. There are no multiple windows. |
|
|
89
|
+
| [`preferredColorScheme`](node_modules/@satinhq/kit/dist/app/appearance.d.ts), [`PreferredColorScheme`](node_modules/@satinhq/kit/dist/app/appearanceStore.d.ts) | Force light or dark for the whole app, or follow the system. runApp also takes an initial preferredColorScheme. | The override covers the whole app, presentations included; one view or sheet cannot differ. Persist the choice with useAppStorage and apply it at launch. |
|
|
90
|
+
| [`NavigationStack`](node_modules/@satinhq/kit/dist/public/runtime.d.ts), [`defineRoutes`](node_modules/@satinhq/kit/dist/public/routes.d.ts), [`route`](node_modules/@satinhq/kit/dist/public/routes.d.ts), [`param`](node_modules/@satinhq/kit/dist/push/schema.d.ts), [`useNavigation`](node_modules/@satinhq/kit/dist/public/runtime.d.ts), [`NavigationLink`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Declare typed routes and navigate with Satin's in-memory stack. | Navigation does not use browser history. Route params must match the declared schema. |
|
|
91
|
+
| [`TabView`](node_modules/@satinhq/kit/dist/public/runtime.d.ts), [`Tab`](node_modules/@satinhq/kit/dist/public/runtime.d.ts) | Each declared tab keeps its own stack, and the selected tab is restored. Tab and TabSection children may arrange the declared tabs, using each id once. | Only the declared tab styles exist. Desktop browsers are not supported. |
|
|
92
|
+
| [`TabSection`](node_modules/@satinhq/kit/dist/tabs/TabSection.d.ts) | Group tabs under collapsible sidebar headers. tabPlacement="sidebarOnly" keeps a group out of the floating and compact tab bars; its tabs keep their stacks. | Only sidebarOnly placement exists: no automatic sections in the top bar, no tab customization and no section header actions. Expansion lasts while the TabView is mounted. With no sidebar, a sidebar-only selection shows the first primary tab. |
|
|
93
|
+
| [`Screen`](node_modules/@satinhq/kit/dist/public/Screen.d.ts) | Set the title and title display through Screen. An untitled root with automatic title display shows no bar unless it has toolbar items or a back button. | Title fonts and sizes follow the system; there is no custom title style. |
|
|
94
|
+
| [`ToolbarItem`](node_modules/@satinhq/kit/dist/public/toolbar.d.ts), [`ToolbarItemGroup`](node_modules/@satinhq/kit/dist/public/toolbar.d.ts), [`ToolbarSpacer`](node_modules/@satinhq/kit/dist/public/toolbar.d.ts) | Declare toolbar items through Screen. subtitle replaces the inline subtitle without growing the bar; largeTitle and largeSubtitle replace the expanded title rows, which scroll away. | Only the placements in ToolbarItemProps exist. |
|
|
95
|
+
| [`List`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`Form`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`Section`](node_modules/@satinhq/kit/dist/list-form/ListForm.d.ts), [`ListRow`](node_modules/@satinhq/kit/dist/list-form/ListForm.d.ts) | List and Form own vertical scrolling, grouped or plain rows, and section headers and footers. | A ListRow is always one row: its children sit side by side. Use one ListRow per row. |
|
|
96
|
+
| [`List`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`Form`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`ListProps`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Choose default or compact section spacing, or a gap in points. scrollContentBackground="hidden" removes the scroll background and keeps row fills. | A numeric gap changes the space between sections; header and footer space stays. visible keeps the default background; it does not make a sheet opaque. |
|
|
97
|
+
| [`ListRow`](node_modules/@satinhq/kit/dist/list-form/ListForm.d.ts) | Set per-row insets, background and separators through ListRowProps. | Satin still owns row geometry. Do not use raw viewport or safe-area CSS in rows. |
|
|
98
|
+
| [`ForEach`](node_modules/@satinhq/kit/dist/list-form/editing.d.ts), [`ListRow`](node_modules/@satinhq/kit/dist/list-form/ListForm.d.ts) | Identify rows by id. onDelete adds swipe-to-delete and the edit-mode delete control; onMove adds the reorder handle and drag. Both receive offsets into the declared rows. | ForEach must sit directly in a List or Section. Moving a selected group, two-finger selection and VoiceOver move actions are not available. |
|
|
99
|
+
| [`moving`](node_modules/@satinhq/kit/dist/list-form/offsets.d.ts), [`removing`](node_modules/@satinhq/kit/dist/list-form/offsets.d.ts) | Apply ForEach's onMove and onDelete offsets to your data: moving(items, { fromOffsets, toOffset }) and removing(items, offsets) return new arrays. | Each returns a new array; store the result in state to update the rows. |
|
|
100
|
+
| [`List`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`EditButton`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`useEditMode`](node_modules/@satinhq/kit/dist/list-form/editing.d.ts), [`ListRow`](node_modules/@satinhq/kit/dist/list-form/ListForm.d.ts) | Select one optional id or a Set of ids. EditButton toggles the screen edit mode, which shows selection circles for a Set. | Rows are identified by their ForEach ids. Edit mode belongs to each screen and cannot be set from outside it. Outside edit mode, plain rows cannot be selected with the keyboard. |
|
|
101
|
+
| [`ScrollView`](node_modules/@satinhq/kit/dist/public/scroll.d.ts), [`ScrollTarget`](node_modules/@satinhq/kit/dist/scroll/ScrollTarget.d.ts) | A named scroll region, vertical by default. Scroll to a ScrollTarget through the ref handle or a scrollPosition binding. A ScrollView outside a screen keeps its position only while mounted. | Scroll targets, pull to refresh and scroll geometry work only on the vertical axis. |
|
|
102
|
+
| [`SafeAreaInset`](node_modules/@satinhq/kit/dist/safe-area/SafeAreaInset.d.ts), [`useSafeAreaInsets`](node_modules/@satinhq/kit/dist/public/environment.d.ts) | Place an accessory on any edge with SafeAreaInset. It shares one inset chain with the navigation bar, the tab bar, bottom bars and the keyboard. A top accessory sits below the bar or large title, and its background reaches the top of the screen. | A top inset under a large title stays at the expanded title edge while the title collapses. On an installed iPhone the status bar area is a flat fill (see top-edge-limitation.md). |
|
|
103
|
+
| [`SafeAreaPadding`](node_modules/@satinhq/kit/dist/safe-area/modifiers.d.ts) | Grow the safe area of the content inside: scroll views inset their content, Lists lay out their cards inside the padded width, and other content is padded. | On a scroll view, bottom padding is a spacer at the end of the content. Nested padding adds up. |
|
|
104
|
+
| [`ContentMargins`](node_modules/@satinhq/kit/dist/safe-area/modifiers.d.ts) | Set content margins for every scroll view inside; a List takes a horizontal margin as its layout margin. | placement="scrollIndicators" has no effect: Satin draws the scroll indicator in the screen frame. |
|
|
105
|
+
| [`SafeAreaBar`](node_modules/@satinhq/kit/dist/safe-area/modifiers.d.ts) | A top or bottom SafeAreaInset with no spacing and its own blur under scrolling content. | The bar uses a CSS backdrop blur, not the navigation bar edge effect, and does not extend the navigation bar. |
|
|
106
|
+
| [`IgnoresSafeArea`](node_modules/@satinhq/kit/dist/safe-area/modifiers.d.ts) | Wrap any view. At the top edge it draws from the top of the screen and keeps its layout slot; a primary scroll view inside runs under the bars; keyboard avoidance keeps a bottom SafeAreaInset above the home indicator. | Only a view at the start of the screen content extends upward. Content that does not scroll does not extend through the bottom edge. |
|
|
107
|
+
| [`Button`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`ControlStyleProvider`](node_modules/@satinhq/kit/dist/public/controlStyle.d.ts) | Use onPress, the built-in control styles, control size and inherited disabled state. buttonBorderShape picks automatic, capsule or a rounded rectangle with a fixed radius. | Only the listed button styles exist. There are no circle or container-concentric borders, and plain and list-row buttons draw no border. A custom ButtonStyle draws the content; Satin keeps the press handling and accessibility. |
|
|
108
|
+
| [`Pressable`](node_modules/@satinhq/kit/dist/press/Pressable.d.ts) | A tap target with no chrome. It dims while pressed and ignores touches that turn into scrolls. | An icon-only Pressable needs an aria-label. |
|
|
109
|
+
| [`Label`](node_modules/@satinhq/kit/dist/public/Label.d.ts), [`LabeledContent`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`RowLabel`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`RowIcon`](node_modules/@satinhq/kit/dist/list-form/ListForm.d.ts) | Compose accessible titles, symbols and values with the framework row and label styles. Leading List Label symbols take the app or control tint; symbols with their own colour keep it. | Labels are not interactive, and a custom LabelStyle must return noninteractive content. |
|
|
110
|
+
| [`Toggle`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Edit a controlled boolean with a switch, a button or a custom ToggleStyle. | Only the switch and button styles are built in; anything else needs a custom ToggleStyle. |
|
|
111
|
+
| [`Picker`](node_modules/@satinhq/kit/dist/public/controls.d.ts), [`Choice`](node_modules/@satinhq/kit/dist/list-form/ListForm.d.ts) | Choose one controlled option with the menu, navigationLink, inline or segmented style. | Only the menu, navigationLink, inline and segmented styles exist. |
|
|
112
|
+
| [`Stepper`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Increment or decrement a controlled number within its bounds. | Controlled only: pass value and onChange. |
|
|
113
|
+
| [`Slider`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Drag a controlled value between min and max (0 and 1 by default), continuously or in steps, with optional tick marks. The held thumb lifts into the glass control lens. | No minimum or maximum value labels and no custom tick marks. The label is for accessibility only, and only the thumb can be dragged. |
|
|
114
|
+
| [`TextField`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Edit controlled text with a prompt and keyboard intent; in a List or Form it becomes the row. axis="vertical" grows up to lineLimit. | textFieldStyle="plain" removes the field chrome. WebKit owns the system keyboard, and text layout cannot be customized. |
|
|
115
|
+
| [`SecureField`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Edit a controlled password through secure system input. | Password manager support is limited to autofill. |
|
|
116
|
+
| [`TextEditor`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Edit controlled multiline text that stays clear of the keyboard. | Text layout cannot be customized. |
|
|
117
|
+
| [`useFocusChain`](node_modules/@satinhq/kit/dist/text-input/focusChain.d.ts) | Register named text fields and move focus through them in order with the return key. | Focus moves only through the fields you register. A custom keyboard is not possible. |
|
|
118
|
+
| [`Sheet`](node_modules/@satinhq/kit/dist/public/presentation.d.ts) | Bind sheet visibility and choose detents; a sheet can host a modal NavigationStack. Supplying selection requires onSelectionChange; without selection the detent is uncontrolled. | Sheets start closed after a relaunch. Persist drafts separately, never the presentation flag. |
|
|
119
|
+
| [`FullScreenCover`](node_modules/@satinhq/kit/dist/public/presentation.d.ts), [`useDismiss`](node_modules/@satinhq/kit/dist/presentation/dismiss.d.ts) | Bind cover visibility. useDismiss pops a pushed screen or closes the presentation it is in. | Covers cannot be swiped away. They start closed after a relaunch. |
|
|
120
|
+
| [`Alert`](node_modules/@satinhq/kit/dist/presentation/Presentation.d.ts), [`ConfirmationDialog`](node_modules/@satinhq/kit/dist/presentation/Presentation.d.ts) | Bind visibility and declare ActionItem actions. An alert text field takes prompt, value and onChange. | Alerts and confirmation dialogs start closed after a relaunch, so a destructive confirmation is never restored open. |
|
|
121
|
+
| [`Menu`](node_modules/@satinhq/kit/dist/public/actions.d.ts), [`ContextMenu`](node_modules/@satinhq/kit/dist/actions/RowActions.d.ts), [`Action`](node_modules/@satinhq/kit/dist/actions/types.d.ts) | One action format for menus, context menus and row swipe actions. | Actions have accessible names, but they do not appear in the VoiceOver Actions rotor. |
|
|
122
|
+
| [`Image`](node_modules/@satinhq/kit/dist/image/Image.d.ts), [`AsyncImage`](node_modules/@satinhq/kit/dist/image/Image.d.ts) | Show packaged or remote images with reserved geometry, placeholders and failure handling. AsyncImage reports empty, success and failure through onPhaseChange. | Remote images use the browser's HTTP cache. onPhaseChange reports loading state; it does not swap in other content. There is no Photos library access. |
|
|
123
|
+
| [`SymbolImage`](node_modules/@satinhq/kit/dist/symbols/Symbol.d.ts), [`SymbolProvider`](node_modules/@satinhq/kit/dist/symbols/Symbol.d.ts) | Draw a named catalogue or provider glyph with a weight, scale and rendering mode. | The bundled symbols are Framework7 Icons 5.0.5 (MIT) plus clean-room glyphs drawn for Satin, not Apple SF Symbols. Keep their copyright and license notices. Provider glyphs need their own provenance. Only shipped or registered names draw. |
|
|
124
|
+
| [`Glass`](node_modules/@satinhq/kit/dist/public/glassValue.d.ts), [`GlassEffect`](node_modules/@satinhq/kit/dist/public/glass.d.ts), [`GlassEffectContainer`](node_modules/@satinhq/kit/dist/glass/GlassEffect.d.ts) | Use the shared WebGPU glass material, and group effects in a GlassEffectContainer so they can blend and morph. | If WebGPU fails for good, release builds fall back to a blur-and-tint material unless strict glass is on; development builds report the failure. |
|
|
125
|
+
| [`useScenePhase`](node_modules/@satinhq/kit/dist/public/environment.d.ts), [`useScreenLifecycle`](node_modules/@satinhq/kit/dist/navigation/navigationContext.d.ts) | Read whether the app is in the foreground, and each screen's appear, cover and disappear lifecycle. | The browser may stop running the app while it is suspended. A screen's lifecycle is separate from the app's foreground state. |
|
|
126
|
+
| [`useSceneStorage`](node_modules/@satinhq/kit/dist/public/environment.d.ts) | Checkpoint a JSON-serializable draft for the current navigation entry; repeated pushes each have their own value. null is allowed where the TypeScript type allows it; at runtime only serializability is checked. | Do not store presentation visibility here. A checkpoint can be lost if the browser evicts storage or the process crashes. |
|
|
127
|
+
| [`useAppStorage`](node_modules/@satinhq/kit/dist/public/environment.d.ts) | Keep a small app preference across relaunches. | Stored in the origin's local storage on this device. It does not sync across devices. |
|
|
128
|
+
| [`useColorScheme`](node_modules/@satinhq/kit/dist/public/environment.d.ts), [`useHorizontalSizeClass`](node_modules/@satinhq/kit/dist/public/environment.d.ts), [`useVerticalSizeClass`](node_modules/@satinhq/kit/dist/public/environment.d.ts) | Read the appearance Satin is drawing and the horizontal and vertical size classes. | Increased contrast is not reported. Size classes are compact or regular only. |
|
|
129
|
+
| [`systemColor`](node_modules/@satinhq/kit/dist/public/colors.d.ts), [`semanticColor`](node_modules/@satinhq/kit/dist/public/colors.d.ts) | systemColor returns the 18 iOS system colours; semanticColor returns content, fill, background, separator and tint colours, which also work in portals. | Values match iOS 27 at normal contrast. Increased contrast and Display P3 are not supported. Semantic label colours and layered secondary or tertiary text can differ slightly from iOS. |
|
|
130
|
+
| [`SensoryButton`](node_modules/@satinhq/kit/dist/haptics/SensoryButton.d.ts) | Play the selection tick through the browser's native switch activation where it is available. | Only selection or false. Keyboard and assistive activation may not tick. |
|
|
131
|
+
| [`collection`](node_modules/@satinhq/kit/dist/data/database.d.ts), [`defineDatabase`](node_modules/@satinhq/kit/dist/data/database.d.ts), [`newId`](node_modules/@satinhq/kit/dist/data/database.d.ts), [`useQuery`](node_modules/@satinhq/kit/dist/data/database.d.ts), [`useRecord`](node_modules/@satinhq/kit/dist/data/database.d.ts), [`Query`](node_modules/@satinhq/kit/dist/data/database.d.ts), [`storageQuota`](node_modules/@satinhq/kit/dist/public/storage.d.ts) | Use the reactive local database with declared schemas and explicit durability. | Data lives in IndexedDB on this device. The browser may evict it, and writes can fail. |
|
|
132
|
+
| [`MediaPlayer`](node_modules/@satinhq/kit/dist/media/types.d.ts), [`useMediaPlayer`](node_modules/@satinhq/kit/dist/media/react.d.ts) | Control the app-wide audio queue and read its playback state. | Audio only, with no video player and no background playback beyond what WebKit allows. Playback depends on WebKit codec support and a server that serves byte ranges. |
|
|
133
|
+
| [`useNotifications`](node_modules/@satinhq/kit/dist/public/environment.d.ts), [`NotificationPermissionExplainer`](node_modules/@satinhq/kit/dist/public/environment.d.ts) | Ask for permission from a user gesture and use push notifications and the badge. | Permission requires the app to be installed on the Home Screen. Local scheduled notifications are unavailable; schedule them from your own authenticated server. |
|
|
134
|
+
| [`useUnsavedChanges`](node_modules/@satinhq/kit/dist/root/runtimeContext.d.ts) | Tell Satin about unsaved work so a pending app update waits. | It only delays app updates; it does not stop the user from dismissing a sheet. |
|
|
135
|
+
| [`useAppUpdate`](node_modules/@satinhq/kit/dist/public/environment.d.ts) | Read whether this launch applied an update, once the app is ready. defineApp advanced.updateProfile "preview" admits Safari tabs and live updates. | Preview builds may reload on update. Release, the default, applies updates only at safe moments. |
|
|
136
|
+
| [`useReachability`](node_modules/@satinhq/kit/dist/reachability/react.d.ts) | Read the network status and whether the app's server answers. | It cannot promise that a request will succeed. |
|
|
137
|
+
| [`Selectable`](node_modules/@satinhq/kit/dist/root/SatinRoot.d.ts), [`Zoomable`](node_modules/@satinhq/kit/dist/zoom/Zoomable.d.ts) | Allow text selection in a region, or pinch to zoom in a bounded region. | Zoomable is the only region that zooms; the page itself never does. There is no general gesture composition. |
|
|
138
|
+
| [`ContentUnavailableView`](node_modules/@satinhq/kit/dist/public/controls.d.ts) | Compose an empty state from a title, a symbol, an optional description and actions. Screens that need the server use it when offline. | Takes an explicit title, icon, description and actions; there is no built-in search variant. |
|
|
139
|
+
| [`NavigationSplitView`](node_modules/@satinhq/kit/dist/public/runtime.d.ts) | Show the declared primary root as a sidebar and its pushes as a retained detail column. At compact width it collapses to a stack. | It renders an existing declared stack; it takes no modal or ad hoc root. |
|
|
140
|
+
| [`Searchable`](node_modules/@satinhq/kit/dist/search/searchable.d.ts), [`SearchScopes`](node_modules/@satinhq/kit/dist/search/searchable.d.ts), [`SearchSuggestion`](node_modules/@satinhq/kit/dist/search/searchable.d.ts), [`SearchFieldPlacement`](node_modules/@satinhq/kit/dist/search/searchable.d.ts) | Pass searchable={{ text, onTextChange, prompt, placement, scopes, suggestions, onSubmit }} to Screen or List. With automatic placement, iPhone uses the bottom toolbar when the screen has no other bottom bar items, and the navigation bar drawer otherwise; iPad and scoped fields use the drawer. The bar owns the field, its clear and close buttons, the scope bar, suggestions and collapse on scroll. isPresented and onPresentedChange control whether search is active. | The bottom toolbar field does not animate in yet and draws no scope bar, so scoped fields stay in the drawer. A search tab draws no bottom field; role="search" is metadata only. Do not build your own search bar. |
|
|
141
|
+
| [`DefaultToolbarItem`](node_modules/@satinhq/kit/dist/public/toolbar.d.ts) | Place <DefaultToolbarItem kind="search" placement="bottomBar" /> in a Screen toolbar to put the search field in the bottom bar beside other items, for example a ToolbarSpacer and a compose button. | Only kind="search". Without a ToolbarSpacer the next item is not merged into the search capsule. iPad keeps the drawer. |
|
|
142
|
+
| [`DatePicker`](node_modules/@satinhq/kit/dist/controls/DatePicker.d.ts) | Compact style: grey value capsules open the system date or time picker. selection is a Date, or a time-zone-free string (YYYY-MM-DD, HH:mm or YYYY-MM-DDTHH:mm) for days that must not shift across time zones. displayedComponents picks the date, the time or both, and in sets the range; out-of-range choices are clamped. | No graphical or wheel style. WebKit adds Reset and Done buttons to the system picker, centres it instead of anchoring it to the capsule, and does not grey out days outside the range. See controls.md. |
|
|
143
|
+
| [`ColorPicker`](node_modules/@satinhq/kit/dist/controls/ColorPicker.d.ts) | A row with a colour well that opens the system colour picker: grid, spectrum, sliders, eyedropper and saved colours. supportsOpacity adds the opacity slider. selection is #RRGGBB or #RRGGBBAA. | The system picker is titled "Colors", not with the label. Output is sRGB hex; Display P3 choices are converted to sRGB. See controls.md. |
|
|
144
|
+
| [`PhotosPicker`](node_modules/@satinhq/kit/dist/public/filePickers.d.ts), [`PhotosPickerProps`](node_modules/@satinhq/kit/dist/public/filePickers.d.ts), [`FileImporter`](node_modules/@satinhq/kit/dist/public/filePickers.d.ts), [`FileImporterProps`](node_modules/@satinhq/kit/dist/public/filePickers.d.ts) | Use the system file chooser to receive photo or document bytes. Cancelling keeps the current selection, and results for a picker that changed meanwhile are dropped. | MIME types are hints, not validation. There is no photo library identifier and no lasting file access, and overlapping choosers cannot always be told apart. Not yet verified in an installed app. |
|
|
145
|
+
| [`ScrollView`](node_modules/@satinhq/kit/dist/public/scroll.d.ts), [`ScrollEdgeEffectStyle`](node_modules/@satinhq/kit/dist/scroll/edgePolicy.d.ts), [`ScrollEdgeEffectHidden`](node_modules/@satinhq/kit/dist/scroll/edgePolicy.d.ts), [`ScrollEdgeSelection`](node_modules/@satinhq/kit/dist/scroll/edgePolicy.d.ts) | Choose soft or automatic material under the top bar, and hide it per edge, through ScrollView props. A boolean applies to the top edge. | The hard style throws an unsupported error. Only the top edge draws material; other edges draw none. |
|
|
146
|
+
| [`Screen`](node_modules/@satinhq/kit/dist/public/Screen.d.ts), [`ToolbarMinimizationBehavior`](node_modules/@satinhq/kit/dist/navigation/toolbarMinimization.d.ts), [`ToolbarMinimizationRestoration`](node_modules/@satinhq/kit/dist/navigation/toolbarMinimization.d.ts), [`ToolbarMinimizationSafeAreaAdjustment`](node_modules/@satinhq/kit/dist/navigation/toolbarMinimization.d.ts) | Opt in to navigation bar minimization on scroll down or up, choose whether it returns on reversal or only at the scroll edge, and whether the content inset adjusts, through Screen or route options. | Navigation bar minimization is opt-in; never keeps the bar expanded. |
|
|
147
|
+
| [`TabView`](node_modules/@satinhq/kit/dist/public/runtime.d.ts) | Show bottomAccessory content in the TabView bottom slot. TabView draws capsule glass behind it; set bottomAccessoryMaterial="custom" when the app draws its own. | There is no minimize behavior or placement hook yet, and the collapse into the tab bar is incomplete. |
|
|
148
|
+
| [`ShareLink`](node_modules/@satinhq/kit/dist/public/deviceActions.d.ts), [`ShareLinkProps`](node_modules/@satinhq/kit/dist/public/deviceActions.d.ts) | Share prepared text, URLs or files through the system share sheet during the press. Check that file sharing is supported before handing files off. | No drag and drop or file provider integration. Completion means the system took the share, not that anyone received it; AbortError also covers having no suitable target. Not yet verified in an installed app. |
|
|
149
|
+
| [`PasteButton`](node_modules/@satinhq/kit/dist/public/deviceActions.d.ts), [`PasteButtonProps`](node_modules/@satinhq/kit/dist/public/deviceActions.d.ts) | Read plain text when the user presses, with the browser permission prompt and delivery scoped to the button. | Plain text only. Dismissal and denial look the same. WebKit may show an extra Paste confirmation. Not yet verified in an installed app. |
|
|
150
|
+
| [`useNamespace`](node_modules/@satinhq/kit/dist/motion/matchedGeometry.d.ts) | In a withAnimation change, a MatchedGeometryEffect view whose id is removed and inserted elsewhere moves from the old frame to the new one while the two cross-fade; a matched view that moves animates from where it was; an unpaired one fades. Motion runs on the compositor as transform and opacity, and the removed view stays on screen until its fade ends. | Matches frames only, around the centre. Corner radius scales with the frame during the flight instead of staying fixed. A non-source view does not follow its source outside an animation. Glass does not travel with a removed view. |
|
|
151
|
+
| [`MatchedTransitionSource`](node_modules/@satinhq/kit/dist/public/navigationTransition.d.ts), [`NavigationTransition`](node_modules/@satinhq/kit/dist/public/navigationTransition.d.ts), [`defineNamespace`](node_modules/@satinhq/kit/dist/motion/matchedGeometry.d.ts) | Mark the view a push starts from with MatchedTransitionSource (id, namespace) and give the pushed Screen navigationTransition={NavigationTransition.zoom({ sourceID, in })}. The screen grows out of the source on push and shrinks back into it on Back, the edge swipe and a downward drag from the top; the screen behind dims and recedes. defineNamespace() shares a namespace between routes. If several visible sources share an id, the one the user tapped is used both ways; if it disappears, navigation falls back to the normal slide. | Pushed screens only; sheets and full-screen covers do not zoom. The source must be on screen, or the push slides. A downward dismiss must start within about 27 degrees of vertical. |
|
|
152
|
+
| [`withAnimation`](node_modules/@satinhq/kit/dist/motion/matchedGeometry.d.ts), [`Animation`](node_modules/@satinhq/kit/dist/motion/animationValue.d.ts), [`SpringOptions`](node_modules/@satinhq/kit/dist/motion/animationValue.d.ts) | Apply synchronous state changes from an event handler; withAnimation returns the callback result and passes errors through. Keyed ForEach rows in a List animate reorders, and experimental MatchedGeometryEffect views also take part. Animation offers default, smooth, snappy, bouncy and spring({ durationMs, bounce }). | Other state and style changes do not animate. There is no null animation, easing curve, repeat, delay, completion callback or per-update timing; use one outer synchronous update. Bounce cannot be negative. |
|
|
153
|
+
| [`useBuildInfo`](node_modules/@satinhq/kit/dist/app/buildInfo.d.ts), [`BuildInfo`](node_modules/@satinhq/kit/dist/app/buildInfo.d.ts) | Read the framework version, unique app build id and build time baked into the running bundle, including offline launches. | The build id is not a git revision or a service worker cache hash. Builds made without satinApp report "unavailable". What the server last served says nothing about which cached bundle is running. |
|
|
154
|
+
| [`Link`](node_modules/@satinhq/kit/dist/web/openURL.d.ts), [`useOpenURL`](node_modules/@satinhq/kit/dist/web/openURL.d.ts), [`WebView`](node_modules/@satinhq/kit/dist/web/WebView.d.ts), [`useWebFrame`](node_modules/@satinhq/kit/dist/web/WebView.d.ts) | Open app URLs through in-memory navigation, hand other URLs to the browser, or embed a sandboxed frame. | You cannot force the external browser. A dispatched URL is not a loaded page. Cross-origin or blocked frames report unverified, and only same-origin frames can be reloaded or stopped. |
|
|
155
|
+
| [`defineWebAuthentication`](node_modules/@satinhq/kit/dist/web/authentication.d.ts), [`useWebAuthentication`](node_modules/@satinhq/kit/dist/web/useWebAuthentication.d.ts) | Prepare a durable authorization-code sign-in with PKCE, start it from a gesture as a popup or redirect, and finish it when the app returns. | Needs a secure context, local storage, Web Locks, a dedicated uncached callback page and a server exchange. Bridge reads need a private transaction proof. Your server validates tokens and OpenID Connect. Completion in the background is not guaranteed. |
|
|
156
|
+
| [`cornerClipPath`](node_modules/@satinhq/kit/dist/shapes/corners.d.ts) | Return a CSS clip path for an explicit width and height: continuous or circular rounded corners, a capsule or an ellipse. Swipe action configurations take the same shapes for the revealed row face. | You size it yourself outside framework rows. It does not change a glass mask. Continuous corners follow the iOS 27 corner curve. |
|
|
157
|
+
| [`useGlassErrors`](node_modules/@satinhq/kit/dist/public/environment.d.ts) | Read installation failures, appearance records and glass errors from Satin's diagnostics. | Diagnostics show what failed; they do not prove the app looks or behaves right on a device. |
|
|
158
|
+
| [`useKeyboardMetrics`](node_modules/@satinhq/kit/dist/public/keyboard.d.ts) | Read the keyboard geometry Satin uses for editing layouts. | It reads the keyboard; it cannot change the keyboard or add a separate keyboard lifecycle. |
|
|
157
159
|
<!-- framework-api:end -->
|
|
158
160
|
|
|
159
161
|
Use `Sheet` for short independent edits, `Alert` for a brief message or text entry, and `ConfirmationDialog` for destructive choices. Each uses `isPresented` and `onPresentedChange`. Give actions stable ids and explicit cancel/destructive roles. Pass the trigger ref as `anchor` for an iPad confirmation. Only the destructive action may write data; handle rejected writes before reporting success. `no-browser-dialog` forbids browser alert, confirm and prompt. See the application recipes for a complete confirmation and failed-save example.
|
|
@@ -54,7 +54,6 @@ import {
|
|
|
54
54
|
NavigationLink,
|
|
55
55
|
type RouteParameters,
|
|
56
56
|
} from '@satinhq/kit'
|
|
57
|
-
import '@satinhq/kit/styles.css'
|
|
58
57
|
import { app as appInput } from './app'
|
|
59
58
|
|
|
60
59
|
const app = defineApp(appInput)
|
|
@@ -124,7 +123,7 @@ For a built Safari-tab preview, add `updateProfile: 'preview'` to the generated
|
|
|
124
123
|
|
|
125
124
|
## Find supported APIs
|
|
126
125
|
|
|
127
|
-
Import app APIs from `@satinhq/kit`, build integration from `@satinhq/kit/vite`, and
|
|
126
|
+
Import app APIs from `@satinhq/kit`, build integration from `@satinhq/kit/vite`, and let `satinApp()` include framework styles before app CSS. `@satinhq/kit/internal` is for framework development; app lint rejects it. `@satinhq/kit/testing` belongs in tests. `@satinhq/kit/unstable` contains experimental compatibility APIs; consult its generated export inventory before use.
|
|
128
127
|
|
|
129
128
|
The generated [API reference](https://github.com/satinhq/satin/blob/main/packages/kit/api/reference.md) describes supported exports and behavior. Its declaration links resolve inside the installed package. See the [package guide](https://github.com/satinhq/satin/blob/main/packages/kit/README.md) for examples. A planned feature does not imply that a React prop exists.
|
|
130
129
|
|
|
@@ -132,6 +131,8 @@ Use `NavigationLink` for a destination, `Button` for an action, `LabeledContent`
|
|
|
132
131
|
|
|
133
132
|
Let the app definition own install metadata and launch backgrounds. Keep the generated status style; components consume framework geometry rather than raw viewport units or safe-area CSS. Satin uses the system font. Do not add font files or recreate missing framework controls in app CSS.
|
|
134
133
|
|
|
134
|
+
Use [Tailwind with Satin](https://github.com/satinhq/satin/blob/main/docs/tailwind.md) for utility classes.
|
|
135
|
+
|
|
135
136
|
Continue with [application recipes](https://github.com/satinhq/satin/blob/main/docs/app-recipes.md), [safe local data and backup restore](https://github.com/satinhq/satin/blob/main/docs/data.md), [geometry and theme tokens](https://github.com/satinhq/satin/blob/main/docs/tokens.md), [networking](https://github.com/satinhq/satin/blob/main/docs/networking.md) and [push sender setup](https://github.com/satinhq/satin/blob/main/packages/push/README.md). The [push relay](https://github.com/satinhq/satin/blob/main/packages/push/README.md) sends immediately; your backend owns reminder scheduling. DatePicker, ColorPicker and ProgressView are available with [documented styles and constraints](https://github.com/satinhq/satin/blob/main/docs/controls.md). Photo/file acquisition has no public chooser at this revision. Read the current limitations before depending on these capabilities.
|
|
136
137
|
|
|
137
138
|
## Screen content and controls
|
|
@@ -211,6 +212,8 @@ Checks run when ready, on foreground return, on reconnect and every five minutes
|
|
|
211
212
|
|
|
212
213
|
At cold launch, a waiting worker can activate offline behind the launch screen. Otherwise lookup, discovery and download share an 800 ms budget, followed by a separate 3-second activation limit. Slow, failed or offline checks keep the cached build usable. Optional download bytes never show update progress until the replacement has claimed this document and a safe reload is committed. First-install progress is unchanged. `advanced.updateActivation: 'cold-launch-or-explicit'` retains the explicit update action; preview/hot reload keeps its explicit development policy.
|
|
213
214
|
|
|
215
|
+
The cover, progress ring and launch/install errors belong to one inline, shadow-isolated pre-launch environment generated by `satinApp()`. They do not require React, application CSS or an active worker. The framework hands off only after its styles and content are ready. If your host sets Content Security Policy, add the per-page script and style hashes from `dist/satin-csp.json` to its existing policy and publish those headers with each build. Do not block the inline launch environment while app resources load.
|
|
216
|
+
|
|
214
217
|
## Public API inventory
|
|
215
218
|
|
|
216
219
|
<!-- public-api:start -->
|
package/template/README.md
CHANGED
|
@@ -41,8 +41,8 @@ reload while developing. Keep important data backed up.
|
|
|
41
41
|
- `src/styles.css` contains optional app typography and spacing.
|
|
42
42
|
|
|
43
43
|
Use `Button` for actions, `NavigationLink` for navigation and `Selectable` for
|
|
44
|
-
prose. Import application components from `@satinhq/kit
|
|
45
|
-
`@satinhq/kit/
|
|
44
|
+
prose. Import application components from `@satinhq/kit` and build integration
|
|
45
|
+
from `@satinhq/kit/vite`. `satinApp()` includes framework styles before app CSS. Diagnostics and
|
|
46
46
|
internal imports are not needed by this starter.
|
|
47
47
|
|
|
48
48
|
## Data and notifications
|
package/template/package.json
CHANGED