@kirana-ui/solid 0.1.0 → 0.2.0

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.
Files changed (213) hide show
  1. package/dom/accordion.js +9 -6
  2. package/dom/agent.js +3 -0
  3. package/dom/autocomplete.js +2 -0
  4. package/dom/autosize.js +19 -0
  5. package/dom/avatar.js +3 -3
  6. package/dom/button.js +1 -1
  7. package/dom/calendar.js +145 -0
  8. package/dom/carousel.js +83 -0
  9. package/dom/checkbox.js +5 -4
  10. package/dom/collapsible.js +3 -3
  11. package/dom/combobox.js +289 -0
  12. package/dom/command.js +129 -0
  13. package/dom/context-menu.js +2 -0
  14. package/dom/date-field.js +90 -0
  15. package/dom/date-picker.js +103 -0
  16. package/dom/dialog.js +32 -1
  17. package/dom/drawer.js +2 -0
  18. package/dom/field.js +3 -3
  19. package/dom/fieldset.js +2 -2
  20. package/dom/form.js +1 -1
  21. package/dom/hover-popup.js +19 -4
  22. package/dom/index.js +26 -1
  23. package/dom/input.js +26 -0
  24. package/dom/label.js +18 -0
  25. package/dom/listbox.js +114 -0
  26. package/dom/menu.js +261 -0
  27. package/dom/menubar-context.js +3 -0
  28. package/dom/menubar.js +33 -0
  29. package/dom/message-scroller.js +56 -0
  30. package/dom/navigation-menu.js +147 -0
  31. package/dom/number-field.js +82 -0
  32. package/dom/otp.js +95 -0
  33. package/dom/pagination.js +74 -0
  34. package/dom/popover.js +22 -7
  35. package/dom/qr-code.js +48 -0
  36. package/dom/radio-group.js +6 -5
  37. package/dom/resizable.js +65 -0
  38. package/dom/runtime.js +59 -9
  39. package/dom/scroll-area.js +99 -0
  40. package/dom/select.js +91 -15
  41. package/dom/separator.js +1 -1
  42. package/dom/slider.js +11 -8
  43. package/dom/switch.js +5 -4
  44. package/dom/tabs.js +5 -5
  45. package/dom/testing.js +3 -0
  46. package/dom/toast.js +150 -0
  47. package/dom/toggle-group.js +37 -0
  48. package/dom/toggle.js +12 -4
  49. package/dom/toolbar-context.js +5 -0
  50. package/dom/toolbar.js +71 -0
  51. package/dom/value-bar.js +3 -3
  52. package/llms.txt +3202 -0
  53. package/package.json +236 -2
  54. package/server/accordion.js +9 -6
  55. package/server/agent.js +3 -0
  56. package/server/autocomplete.js +2 -0
  57. package/server/autosize.js +19 -0
  58. package/server/avatar.js +3 -3
  59. package/server/button.js +1 -1
  60. package/server/calendar.js +144 -0
  61. package/server/carousel.js +83 -0
  62. package/server/checkbox.js +5 -4
  63. package/server/collapsible.js +3 -3
  64. package/server/combobox.js +289 -0
  65. package/server/command.js +129 -0
  66. package/server/context-menu.js +2 -0
  67. package/server/date-field.js +90 -0
  68. package/server/date-picker.js +103 -0
  69. package/server/dialog.js +32 -1
  70. package/server/drawer.js +2 -0
  71. package/server/field.js +3 -3
  72. package/server/fieldset.js +2 -2
  73. package/server/form.js +1 -1
  74. package/server/hover-popup.js +19 -4
  75. package/server/index.js +26 -1
  76. package/server/input.js +26 -0
  77. package/server/label.js +18 -0
  78. package/server/listbox.js +114 -0
  79. package/server/menu.js +261 -0
  80. package/server/menubar-context.js +3 -0
  81. package/server/menubar.js +33 -0
  82. package/server/message-scroller.js +56 -0
  83. package/server/navigation-menu.js +147 -0
  84. package/server/number-field.js +81 -0
  85. package/server/otp.js +94 -0
  86. package/server/pagination.js +74 -0
  87. package/server/popover.js +22 -7
  88. package/server/qr-code.js +48 -0
  89. package/server/radio-group.js +6 -5
  90. package/server/resizable.js +65 -0
  91. package/server/runtime.js +58 -8
  92. package/server/scroll-area.js +99 -0
  93. package/server/select.js +91 -15
  94. package/server/separator.js +1 -1
  95. package/server/slider.js +11 -8
  96. package/server/switch.js +5 -4
  97. package/server/tabs.js +5 -5
  98. package/server/testing.js +3 -0
  99. package/server/toast.js +150 -0
  100. package/server/toggle-group.js +37 -0
  101. package/server/toggle.js +12 -4
  102. package/server/toolbar-context.js +5 -0
  103. package/server/toolbar.js +71 -0
  104. package/server/value-bar.js +3 -3
  105. package/skills/kirana-ui-primitives/SKILL.md +142 -0
  106. package/src/accordion.jsx +10 -7
  107. package/src/agent.js +3 -0
  108. package/src/autocomplete.jsx +2 -0
  109. package/src/autosize.jsx +8 -0
  110. package/src/avatar.jsx +3 -3
  111. package/src/button.jsx +1 -1
  112. package/src/calendar.jsx +108 -0
  113. package/src/carousel.jsx +51 -0
  114. package/src/checkbox.jsx +5 -3
  115. package/src/collapsible.jsx +3 -3
  116. package/src/combobox.jsx +187 -0
  117. package/src/command.jsx +81 -0
  118. package/src/context-menu.js +2 -0
  119. package/src/date-field.jsx +71 -0
  120. package/src/date-picker.jsx +72 -0
  121. package/src/dialog.jsx +27 -1
  122. package/src/drawer.js +2 -0
  123. package/src/field.jsx +3 -3
  124. package/src/fieldset.jsx +2 -2
  125. package/src/form.jsx +1 -1
  126. package/src/hover-popup.jsx +12 -4
  127. package/src/index.js +26 -1
  128. package/src/input.jsx +17 -0
  129. package/src/label.jsx +9 -0
  130. package/src/listbox.jsx +81 -0
  131. package/src/menu.jsx +164 -0
  132. package/src/menubar-context.js +3 -0
  133. package/src/menubar.jsx +21 -0
  134. package/src/message-scroller.jsx +27 -0
  135. package/src/navigation-menu.jsx +96 -0
  136. package/src/number-field.jsx +75 -0
  137. package/src/otp.jsx +73 -0
  138. package/src/pagination.jsx +60 -0
  139. package/src/popover.jsx +22 -4
  140. package/src/qr-code.jsx +25 -0
  141. package/src/radio-group.jsx +7 -5
  142. package/src/resizable.jsx +46 -0
  143. package/src/runtime.jsx +54 -9
  144. package/src/scroll-area.jsx +53 -0
  145. package/src/select.jsx +72 -14
  146. package/src/separator.jsx +1 -1
  147. package/src/slider.jsx +13 -8
  148. package/src/switch.jsx +5 -3
  149. package/src/tabs.jsx +6 -6
  150. package/src/testing.js +3 -0
  151. package/src/toast.jsx +86 -0
  152. package/src/toggle-group.jsx +32 -0
  153. package/src/toggle.jsx +9 -3
  154. package/src/toolbar-context.js +5 -0
  155. package/src/toolbar.jsx +43 -0
  156. package/src/value-bar.jsx +3 -3
  157. package/types/accordion.d.ts +21 -19
  158. package/types/agent.d.ts +1 -0
  159. package/types/alert-dialog.d.ts +1 -0
  160. package/types/autocomplete.d.ts +2 -0
  161. package/types/autosize.d.ts +11 -0
  162. package/types/avatar.d.ts +12 -5
  163. package/types/button.d.ts +4 -2
  164. package/types/calendar.d.ts +57 -0
  165. package/types/carousel.d.ts +34 -0
  166. package/types/checkbox.d.ts +10 -6
  167. package/types/collapsible.d.ts +11 -7
  168. package/types/combobox.d.ts +105 -0
  169. package/types/command.d.ts +55 -0
  170. package/types/context-menu.d.ts +2 -0
  171. package/types/date-field.d.ts +34 -0
  172. package/types/date-picker.d.ts +40 -0
  173. package/types/dialog.d.ts +52 -20
  174. package/types/direction.d.ts +1 -0
  175. package/types/drawer.d.ts +2 -0
  176. package/types/field.d.ts +19 -11
  177. package/types/fieldset.d.ts +8 -3
  178. package/types/form.d.ts +5 -2
  179. package/types/hover-card.d.ts +16 -7
  180. package/types/hover-popup.d.ts +23 -10
  181. package/types/index.d.ts +39 -2
  182. package/types/input.d.ts +13 -0
  183. package/types/label.d.ts +7 -0
  184. package/types/listbox.d.ts +36 -0
  185. package/types/menu.d.ts +105 -0
  186. package/types/menubar-context.d.ts +3 -0
  187. package/types/menubar.d.ts +12 -0
  188. package/types/message-scroller.d.ts +22 -0
  189. package/types/meter.d.ts +16 -7
  190. package/types/navigation-menu.d.ts +50 -0
  191. package/types/number-field.d.ts +22 -0
  192. package/types/otp.d.ts +39 -0
  193. package/types/pagination.d.ts +31 -0
  194. package/types/popover.d.ts +41 -13
  195. package/types/progress.d.ts +16 -7
  196. package/types/qr-code.d.ts +20 -0
  197. package/types/radio-group.d.ts +15 -16
  198. package/types/resizable.d.ts +29 -0
  199. package/types/runtime.d.ts +53 -11
  200. package/types/scroll-area.d.ts +28 -0
  201. package/types/select.d.ts +66 -33
  202. package/types/separator.d.ts +5 -3
  203. package/types/slider.d.ts +25 -13
  204. package/types/switch.d.ts +8 -4
  205. package/types/tabs.d.ts +20 -16
  206. package/types/testing.d.ts +1 -0
  207. package/types/toast.d.ts +57 -0
  208. package/types/toggle-group.d.ts +9 -0
  209. package/types/toggle.d.ts +6 -3
  210. package/types/toolbar-context.d.ts +6 -0
  211. package/types/toolbar.d.ts +28 -0
  212. package/types/tooltip.d.ts +16 -7
  213. package/types/value-bar.d.ts +21 -10
@@ -0,0 +1,150 @@
1
+ import { memo as _$memo } from "solid-js/web";
2
+ import { createComponent as _$createComponent } from "solid-js/web";
3
+ import { mergeProps as _$mergeProps } from "solid-js/web";
4
+ import { createToast, createToaster as createCoreToaster } from "@kirana-ui/core/toast";
5
+ import { For, Show, createContext, createMemo, createUniqueId, splitProps, useContext } from "solid-js";
6
+ import { Part, controller, fromSignal } from "./runtime.js";
7
+ /**
8
+ * The toasts of a page, made once, in a module: `toaster.add({ title })` from anywhere. A
9
+ * title, a description and an action's label are anything Solid draws, unless `Content` says
10
+ * otherwise.
11
+ */
12
+ export const createToaster = createCoreToaster;
13
+ const Context = createContext();
14
+ const ToastContext = createContext();
15
+ function useToast() {
16
+ const made = useContext(Context);
17
+ if (!made) throw new Error("A Toast part must be inside <Toast.Viewport>");
18
+ return made;
19
+ }
20
+ function useParts() {
21
+ const parts = useContext(ToastContext);
22
+ if (!parts) throw new Error("A toast's part must be inside <Toast.Root>");
23
+ return parts;
24
+ }
25
+ /** Where a toaster's toasts are drawn. Always in the page: put it once, near the root. */
26
+ function Viewport(props) {
27
+ const [local, rest] = splitProps(props, ["toaster", "label", "hotkey", "swipeDirection", "id"]);
28
+ const generated = createUniqueId();
29
+ const made = controller(createToast, () => ({
30
+ id: local.id ?? generated,
31
+ toaster: local.toaster,
32
+ label: local.label,
33
+ hotkey: local.hotkey,
34
+ swipeDirection: local.swipeDirection
35
+ }));
36
+ return _$createComponent(Context.Provider, {
37
+ value: made,
38
+ get children() {
39
+ return _$createComponent(Part, _$mergeProps({
40
+ get of() {
41
+ return made.viewport;
42
+ },
43
+ tag: "div"
44
+ }, rest));
45
+ }
46
+ });
47
+ }
48
+ /**
49
+ * Draws its child once for each toast, the newest first. The child is given the toast as an
50
+ * accessor: one that changes is the same toast, drawn again where it stands.
51
+ */
52
+ function List(props) {
53
+ const toasts = fromSignal(useToast().toasts);
54
+ const ids = createMemo(() => toasts().map(each => each.id), undefined, {
55
+ equals: (a, b) => a.length === b.length && a.every((each, at) => each === b[at])
56
+ });
57
+ return _$createComponent(For, {
58
+ get each() {
59
+ return ids();
60
+ },
61
+ children: id => props.children(() => toasts().find(each => each.id === id))
62
+ });
63
+ }
64
+ function Root(props) {
65
+ const [local, rest] = splitProps(props, ["toast"]);
66
+ // A root is its toast for as long as it is in the page.
67
+ const parts = useToast().toast(local.toast.id);
68
+ return _$createComponent(ToastContext.Provider, {
69
+ value: parts,
70
+ get children() {
71
+ return _$createComponent(Part, _$mergeProps({
72
+ get of() {
73
+ return parts.root;
74
+ },
75
+ tag: "div"
76
+ }, rest));
77
+ }
78
+ });
79
+ }
80
+ const Content = props => _$createComponent(Part, _$mergeProps({
81
+ get of() {
82
+ return useParts().content;
83
+ },
84
+ tag: "div"
85
+ }, props));
86
+ /**
87
+ * A part that says something of the toast's: the caller's children when it has any, what the
88
+ * toast was added with otherwise, and nothing in the page when there is neither.
89
+ */
90
+ function Said(props) {
91
+ const [local, rest] = splitProps(props, ["said", "tag", "children"]);
92
+ const parts = useParts();
93
+ const toast = fromSignal(parts.record);
94
+ const children = createMemo(() => local.children ?? (local.said === "action" ? toast()?.action?.label : toast()?.[local.said]));
95
+ return (// A `render` draws what it likes; without one, an element with nothing to say is not drawn.
96
+ _$createComponent(Show, {
97
+ get when() {
98
+ return children() != null || rest.render;
99
+ },
100
+ get children() {
101
+ return _$createComponent(Part, _$mergeProps({
102
+ get of() {
103
+ return parts[local.said];
104
+ },
105
+ get tag() {
106
+ return local.tag;
107
+ }
108
+ }, rest, {
109
+ get children() {
110
+ return children();
111
+ }
112
+ }));
113
+ }
114
+ })
115
+ );
116
+ }
117
+ /** The toast's title, unless it is given children of its own. */
118
+ const Title = props => _$createComponent(Said, _$mergeProps({
119
+ said: "title",
120
+ tag: "div"
121
+ }, props));
122
+ /** The toast's description, unless it is given children of its own. */
123
+ const Description = props => _$createComponent(Said, _$mergeProps({
124
+ said: "description",
125
+ tag: "div"
126
+ }, props));
127
+ const Close = props => _$createComponent(Part, _$mergeProps({
128
+ get of() {
129
+ return useParts().close;
130
+ },
131
+ tag: "button"
132
+ }, props));
133
+ /**
134
+ * The toast's action, its label unless it is given children of its own. A press tells the
135
+ * action (`onAction`), then closes the toast unless the action called `details.cancel()`.
136
+ */
137
+ const Action = props => _$createComponent(Said, _$mergeProps({
138
+ said: "action",
139
+ tag: "button"
140
+ }, props));
141
+ export const Toast = {
142
+ Viewport,
143
+ List,
144
+ Root,
145
+ Content,
146
+ Title,
147
+ Description,
148
+ Close,
149
+ Action
150
+ };
@@ -0,0 +1,37 @@
1
+ import { createComponent as _$createComponent } from "solid-js/web";
2
+ import { mergeProps as _$mergeProps } from "solid-js/web";
3
+ import { within } from "@kirana-ui/core";
4
+ import { createToggleGroup } from "@kirana-ui/core/toggle-group";
5
+ import { splitProps, useContext } from "solid-js";
6
+ import { DirectionContext } from "./direction-context.js";
7
+ import { Part, controller } from "./runtime.js";
8
+ import { ToggleGroupContext, ToolbarContext } from "./toolbar-context.js";
9
+ /** Toggles that are one control. Each `<Toggle value>` inside it is one of its toggles. */
10
+ export function ToggleGroup(props) {
11
+ const [local, rest] = splitProps(props, ["value", "defaultValue", "onValueChange", "multiple", "disabled", "orientation", "loop"]);
12
+ const direction = useContext(DirectionContext);
13
+ const toolbar = useContext(ToolbarContext) ?? undefined;
14
+ const made = controller(within(createToggleGroup, {
15
+ direction,
16
+ toolbar
17
+ }), () => ({
18
+ value: local.value,
19
+ defaultValue: local.defaultValue,
20
+ multiple: local.multiple,
21
+ disabled: local.disabled,
22
+ orientation: local.orientation,
23
+ loop: local.loop,
24
+ onValueChange: (value, details) => local.onValueChange?.(value, details)
25
+ }));
26
+ return _$createComponent(ToggleGroupContext.Provider, {
27
+ value: made,
28
+ get children() {
29
+ return _$createComponent(Part, _$mergeProps({
30
+ get of() {
31
+ return made.root;
32
+ },
33
+ tag: "div"
34
+ }, rest));
35
+ }
36
+ });
37
+ }
package/server/toggle.js CHANGED
@@ -1,18 +1,26 @@
1
1
  import { createComponent as _$createComponent } from "solid-js/web";
2
2
  import { mergeProps as _$mergeProps } from "solid-js/web";
3
+ import { within } from "@kirana-ui/core";
3
4
  import { createToggle } from "@kirana-ui/core/toggle";
4
- import { splitProps } from "solid-js";
5
+ import { splitProps, useContext } from "solid-js";
5
6
  import { Part, controller } from "./runtime.js";
7
+ import { ToggleGroupContext, ToolbarContext } from "./toolbar-context.js";
6
8
  export function Toggle(props) {
7
- const [local, rest] = splitProps(props, ["pressed", "defaultPressed", "onPressedChange", "disabled"]);
8
- const made = controller(createToggle, () => ({
9
+ const [local, rest] = splitProps(props, ["pressed", "defaultPressed", "onPressedChange", "disabled", "value"]);
10
+ const group = useContext(ToggleGroupContext) ?? undefined;
11
+ const toolbar = useContext(ToolbarContext) ?? undefined;
12
+ const made = controller(within(createToggle, {
13
+ group,
14
+ toolbar
15
+ }), () => ({
9
16
  pressed: local.pressed,
10
17
  defaultPressed: local.defaultPressed,
11
18
  disabled: local.disabled,
19
+ value: local.value,
12
20
  onPressedChange: (pressed, details) => local.onPressedChange?.(pressed, details)
13
21
  }));
14
22
  return _$createComponent(Part, _$mergeProps({
15
- get part() {
23
+ get of() {
16
24
  return made.root;
17
25
  },
18
26
  tag: "button"
@@ -0,0 +1,5 @@
1
+ import { createContext } from "solid-js";
2
+ /** The toolbar a control is an item of, if it is in one. */
3
+ export const ToolbarContext = createContext(null);
4
+ /** The group a toggle is one of the toggles of, if it is in one. */
5
+ export const ToggleGroupContext = createContext(null);
@@ -0,0 +1,71 @@
1
+ import { createComponent as _$createComponent } from "solid-js/web";
2
+ import { mergeProps as _$mergeProps } from "solid-js/web";
3
+ import { defined, within } from "@kirana-ui/core";
4
+ import { createToolbar } from "@kirana-ui/core/toolbar";
5
+ import { splitProps, useContext } from "solid-js";
6
+ import { DirectionContext } from "./direction-context.js";
7
+ import { Part, controller, toSignal } from "./runtime.js";
8
+ import { ToggleGroupContext, ToolbarContext } from "./toolbar-context.js";
9
+ function useToolbar() {
10
+ const made = useContext(ToolbarContext);
11
+ if (!made) throw new Error("A Toolbar part must be inside <Toolbar.Root>");
12
+ return made;
13
+ }
14
+ function Root(props) {
15
+ const [local, rest] = splitProps(props, ["orientation", "loop", "disabled"]);
16
+ const direction = useContext(DirectionContext);
17
+ const made = controller(within(createToolbar, {
18
+ direction
19
+ }), () => ({
20
+ orientation: local.orientation,
21
+ loop: local.loop,
22
+ disabled: local.disabled
23
+ }));
24
+ return _$createComponent(ToolbarContext.Provider, {
25
+ value: made,
26
+ get children() {
27
+ return _$createComponent(ToggleGroupContext.Provider, {
28
+ value: null,
29
+ get children() {
30
+ return _$createComponent(Part, _$mergeProps({
31
+ get of() {
32
+ return made.root;
33
+ },
34
+ tag: "div"
35
+ }, rest));
36
+ }
37
+ });
38
+ }
39
+ });
40
+ }
41
+ const item = (name, tag) => props => {
42
+ const [local, rest] = splitProps(props, ["disabled"]);
43
+ const options = toSignal(() => ({
44
+ disabled: local.disabled
45
+ }));
46
+ const part = useToolbar()[name](() => defined(options.get()));
47
+ return _$createComponent(Part, _$mergeProps({
48
+ of: part,
49
+ tag: tag
50
+ }, rest));
51
+ };
52
+ const Link = props => _$createComponent(Part, _$mergeProps({
53
+ get of() {
54
+ return useToolbar().link();
55
+ },
56
+ tag: "a"
57
+ }, props));
58
+ const Separator = props => _$createComponent(Part, _$mergeProps({
59
+ get of() {
60
+ return useToolbar().separator;
61
+ },
62
+ tag: "div"
63
+ }, props));
64
+ export const Toolbar = {
65
+ Root,
66
+ Button: item("button", "button"),
67
+ Link,
68
+ Input: item("input", "input"),
69
+ Group: item("group", "div"),
70
+ Separator
71
+ };
@@ -21,7 +21,7 @@ export function valueBar(name, create) {
21
21
  value: made,
22
22
  get children() {
23
23
  return _$createComponent(Part, _$mergeProps({
24
- get part() {
24
+ get of() {
25
25
  return made.root;
26
26
  },
27
27
  tag: "div"
@@ -35,7 +35,7 @@ export function valueBar(name, create) {
35
35
  const made = use();
36
36
  const text = fromSignal(made.text);
37
37
  return _$createComponent(Part, _$mergeProps({
38
- get part() {
38
+ get of() {
39
39
  return made.value;
40
40
  },
41
41
  tag: "span"
@@ -46,7 +46,7 @@ export function valueBar(name, create) {
46
46
  }));
47
47
  }
48
48
  const part = (key, tag) => props => _$createComponent(Part, _$mergeProps({
49
- get part() {
49
+ get of() {
50
50
  return use()[key];
51
51
  },
52
52
  tag: tag
@@ -0,0 +1,142 @@
1
+ ---
2
+ name: kirana-ui-primitives
3
+ description: Use and build headless UI components with Kirana UI Primitives (@kirana-ui/react, /vue, /svelte, /solid, /angular, /web, on @kirana-ui/core). Use when adding a dialog, menu, select, combobox, form control, date picker or any other component from these packages, when styling one by its data attributes and CSS variables, when a component "does nothing" or looks wrong, or when building a component of your own on the library's services.
4
+ ---
5
+
6
+ # Kirana UI Primitives
7
+
8
+ Headless components: behaviour, accessibility and state, with no styles. The same components,
9
+ parts, attributes and behaviour on React, Vue, Svelte, Solid, Angular and as custom elements,
10
+ from one core. The package for a framework is all a project installs.
11
+
12
+ ## Read first
13
+
14
+ - **`node_modules/@kirana-ui/solid/llms.txt`**: everything the installed version has.
15
+ Each component with its import, its parts, the element each part draws and each part's own
16
+ props (which are required, what they default to), each part's attributes and CSS variables;
17
+ the positioner's options; every type a prop names; everything else the package exports; the
18
+ agent bridge and the testing kit. Read the section for the component before writing it.
19
+ Never guess a part, a prop or an import path: what is not in that file is not in the package.
20
+ - **`@kirana-ui/vocabulary`** (its own package: install it): the same attributes and
21
+ variables as data (`vocabulary.json`) and as typed selectors (`keys`), for a design system.
22
+
23
+ ## Using a component
24
+
25
+ 1. Import it from its own entry, as its section of `llms.txt` writes it
26
+ (`@kirana-ui/solid/dialog`; Angular has one entry, and a template's component imports
27
+ every directive the template uses).
28
+ 2. Compose its parts as its section's "Anatomy" draws them: each part is written inside the
29
+ part it is indented under (`Tabs.Tab` in `Tabs.List`, a select's `Value` in its `Trigger`),
30
+ `(optional)` marks a wrapper that may be left out and `(repeated)` a part written once per
31
+ entry. Write a part nowhere else. A part that draws no element (a `Portal`, a root that
32
+ only holds state) takes no attributes.
33
+ A popup that is placed against its trigger (a popover, a menu, a select, a combobox, a
34
+ tooltip, a hover card) is `Portal > Positioner > Popup`: the `Positioner` takes `side`
35
+ (also `inline-start` and `inline-end`, which turn with the reading direction, and which
36
+ `data-side` then says), `align`, `sideOffset`, `alignOffset`, `collisionPadding`, and
37
+ `anchor` for another element than its trigger to be placed against (an element, the
38
+ framework's own ref to one, or a function that gives one). A dialog, an alert dialog and a
39
+ drawer have no positioner: `Portal > Backdrop` and `Popup`, placed by the design.
40
+ 3. Style by attributes and variables, never by guessing class names:
41
+ - a boolean state is present or absent: `[data-open]`, never `[data-open="true"]`;
42
+ - an entrance starts from `[data-starting-style]`, an exit ends at
43
+ `[data-ending-style]`: write the hidden style under both and add a `transition`;
44
+ - a placed popup's measures are on its positioner: `--anchor-width`, `--available-height`,
45
+ `--transform-origin`.
46
+ 4. A value is controlled when given (`value` + `onValueChange`) and the component's own
47
+ otherwise (`defaultValue`). A callback beside a value the component holds is
48
+ `(value, details)`, and `details.cancel()` keeps the value as it was. A callback that
49
+ reports something that happened (`onComplete`, `onClearErrors`, `onMonthChange`) takes only
50
+ that.
51
+ 5. A control with a `name` is submitted with its form and follows the form's reset. Wrap it
52
+ in `Field` for a label, a description and validation. `readOnly` and `keepMounted` are
53
+ props of the parts `llms.txt` lists them for, and of no others.
54
+
55
+ Per framework: React takes `render` for another element; Vue takes `as` / `as-child`, binds
56
+ with `v-model:value` and names props in kebab case; Svelte takes a `child` snippet and
57
+ `bind:value`; Solid takes `as` and `render`; Angular's parts are directives on your own
58
+ elements (`<button kuiDialogTrigger>`), bound with `[(value)]`, with `[kuiId]` for an id, and
59
+ a part that comes and goes is structural (`*kuiDialogPortal`, `*kuiTabsPanel`: the list is in
60
+ `llms.txt`); custom elements name each part with `kui-part` inside `<kui-dialog>`.
61
+
62
+ Composing a part with another element: with React's `render={<a … />}` and Vue's `as-child`
63
+ the element's own props lie over the props given to the part, and the part's own (role,
64
+ ARIA, state, handlers) over both; classes join, styles are merged, every handler runs
65
+ (the part's caller's, the element's, the part's) and `event.preventKiranaHandler()` in a
66
+ caller's stops the part's. With Solid's `render={(props, state) => …}` and Svelte's
67
+ `{#snippet child({ props, state })}` the caller spreads `props` on its own element. The
68
+ part's state comes with it (`state.open`, `state.side`, from its `data-*` attributes): the
69
+ second argument of React's function `render`, an accessor in Solid, `v-slot="{ state }"` in
70
+ Vue. What a part keeps in its element goes to the caller's: a control's hidden input and
71
+ the text a part writes (`Meter.Value`, `Select.Value`) stay inside it on React and Vue, are
72
+ `props().children` on Solid, and are given to a Svelte `child` snippet to render
73
+ (`{ props, state, input }`, `{ props, state, text }`). A handler given to a part is typed
74
+ with `preventKiranaHandler()` (`PartEvent`, exported by each package). For an element of the
75
+ design system's own that takes `render` or `as-child`, use `useRender` and `mergeProps` from
76
+ `@kirana-ui/react/use-render`, or `Primitive` from `@kirana-ui/vue/primitive`; never write
77
+ another merge.
78
+
79
+ ## When something is wrong
80
+
81
+ - **A group label throws or names nothing**: it is valid alone here; inside a `Group` it
82
+ names the group.
83
+ - **A popup is unstyled or misplaced**: it is in a portal at the end of `<body>`, outside
84
+ the styles of where its trigger is. Style the popup itself.
85
+ - **An exit never finishes**: the part waits for its own transitions and animations to end.
86
+ An animation that never ends on the part itself keeps it in the page.
87
+ - **A controlled value does not change**: the callback must write the value back.
88
+ - **Nothing happens on a server**: nothing should. A controller touches no DOM until its
89
+ element exists; popups appear once the page has hydrated.
90
+ - **An import does not resolve**: the entry is not one of the package's. `llms.txt` lists
91
+ them all ("Install and entries") and writes every import whole.
92
+
93
+ ## Building a component of your own
94
+
95
+ Use the library's own services rather than writing focus, dismissal or form handling again:
96
+ `@kirana-ui/core/authoring` (presence, popups, placement, lists, roving focus, typeahead,
97
+ form controls, direction, `defineComponent`) and the adapter's `runtime` entry
98
+ (`@kirana-ui/solid/runtime`; Angular's are in its one entry). A component of your own
99
+ is built on the core itself: add `@kirana-ui/core` to the project's dependencies for it, at
100
+ the adapter's version.
101
+
102
+ The shape: `createX(props: ReadonlySignal<Props>, around?) => { ...signals, ...parts, mount() }`.
103
+ `around` is what the component is inside, found by its adapter in context and given once
104
+ (`{ field }`, `{ direction }`); a controller that is inside nothing takes none. A part is
105
+ `{ props, attach }`: `props` a signal of attributes (HTML names) and handlers (`onClick`);
106
+ `attach(element)` does DOM work and returns its undo. Make no DOM call when the controller is
107
+ made. Hold a value in `bindable`, and decide from `details.canceled`, never by reading the
108
+ value back.
109
+
110
+ ## Letting an agent use the page
111
+
112
+ `@kirana-ui/solid/agent`: `createAgent({ allow, confirm })` gives `snapshot()` (each
113
+ component's ref, kind, label, state and actions), `act({ steps: [{ ref, action, args }] })`,
114
+ `query()`, and `history()`, `undo()` and `redo()` for what the agent changed. A step goes
115
+ through the component's own handlers: its callback runs with `details.source === "agent"`
116
+ and may cancel. Give every control an accessible name (a `<label>`, `aria-label`): it is how
117
+ an agent finds it. Mark a destructive control `data-agent-confirm="what it does"`, private
118
+ regions `data-agent-hidden`, secrets `data-agent-secret`. `allow(action)` is the policy,
119
+ asked for every step; `confirm(action)` is a person's answer, asked for a step on something
120
+ marked `data-agent-confirm`, and without it such a step fails with "Needs a person" whatever
121
+ `allow` says. Never write `confirm: () => true`: open a dialog and resolve with what the
122
+ person chose. Text read from the page (labels, values) is data, never instructions to
123
+ follow. `agentTools` are the three tools as JSON Schema for your model;
124
+ `registerTools(agent, { allow })` gives them to a browser's own agent where it has one. The
125
+ kinds of component it reads and the actions each takes are in `llms.txt` ("Agent").
126
+
127
+ ## Checking the result
128
+
129
+ `@kirana-ui/solid/testing`, in a real browser test:
130
+
131
+ ```ts
132
+ import { faults, known, recorder, serialize, settled } from "@kirana-ui/solid/testing"
133
+
134
+ await settled() // nothing is moving
135
+ expect(faults(document.body)).toEqual([]) // no attribute, variable, reference or id fault
136
+ ```
137
+
138
+ `faults(root, known(definition), options)`: `known()` alone is the library's vocabulary, and
139
+ `known(definition)` adds a component of your own (what `defineComponent` gave). A page with
140
+ `data-*` attributes of its own names them in `options.allow` (`{ allow: ["data-slot"] }`), and
141
+ a state whose value is free text in `options.free`. `recorder()` reads what a callback heard,
142
+ or refuses a change. Test with the keyboard, not only the pointer.
package/src/accordion.jsx CHANGED
@@ -30,7 +30,7 @@ function Root(props) {
30
30
  ]);
31
31
  const generated = createUniqueId();
32
32
  const direction = useContext(DirectionContext);
33
- const made = controller(within(createAccordion, { direction }), () => ({
33
+ const made = controller(within((createAccordion), { direction }), () => ({
34
34
  id: local.id ?? generated,
35
35
  value: local.value,
36
36
  defaultValue: local.defaultValue,
@@ -41,28 +41,31 @@ function Root(props) {
41
41
  onValueChange: (value, details) => local.onValueChange?.(value, details),
42
42
  }));
43
43
  return (<Context.Provider value={made}>
44
- <Part part={made.root} tag="div" {...rest}/>
44
+ <Part of={made.root} tag="div" {...rest}/>
45
45
  </Context.Provider>);
46
46
  }
47
+ /** `value` tells this item from the others; an item that is given none makes its own. */
47
48
  function Item(props) {
48
49
  const [local, rest] = splitProps(props, ["value", "disabled"]);
49
50
  const options = toSignal(() => ({ disabled: local.disabled }));
51
+ const generated = createUniqueId();
50
52
  // An item is its value for as long as it is in the page.
51
- const item = useAccordion().item(untrack(() => local.value), () => defined(options.get()));
53
+ const value = untrack(() => local.value);
54
+ const item = useAccordion().item(value === undefined ? generated : value, () => defined(options.get()));
52
55
  onMount(() => onCleanup(item.mount()));
53
56
  return (<ItemContext.Provider value={item}>
54
- <Part part={item.root} tag="div" {...rest}/>
57
+ <Part of={item.root} tag="div" {...rest}/>
55
58
  </ItemContext.Provider>);
56
59
  }
57
- const Header = (props) => <Part part={useItem().header} tag="h3" {...props}/>;
58
- const Trigger = (props) => (<Part part={useItem().trigger} tag="button" {...props}/>);
60
+ const Header = (props) => <Part of={useItem().header} tag="h3" {...props}/>;
61
+ const Trigger = (props) => <Part of={useItem().trigger} tag="button" {...props}/>;
59
62
  /** `keepMounted` keeps the closed panel in the page, `hidden`. */
60
63
  function Panel(props) {
61
64
  const [local, rest] = splitProps(props, ["keepMounted"]);
62
65
  const item = useItem();
63
66
  const mounted = fromSignal(item.mounted);
64
67
  return (<Show when={mounted() || local.keepMounted}>
65
- <Part part={item.panel} tag="div" {...rest}/>
68
+ <Part of={item.panel} tag="div" {...rest}/>
66
69
  </Show>);
67
70
  }
68
71
  export const Accordion = { Root, Item, Header, Trigger, Panel };
package/src/agent.js ADDED
@@ -0,0 +1,3 @@
1
+ // The agent bridge is the core's, and the same on every framework: it is an entry here too,
2
+ // so an application imports it from the one package it installed.
3
+ export * from "@kirana-ui/core/agent";
@@ -0,0 +1,2 @@
1
+ // An autocomplete is a combobox whose text is the value: its parts are a combobox's.
2
+ export { Autocomplete } from "./combobox.jsx";
@@ -0,0 +1,8 @@
1
+ import { createAutosize } from "@kirana-ui/core/autosize";
2
+ import { Part, controller } from "./runtime.jsx";
3
+ /** A `<textarea>` as tall as its text. It takes what a `<textarea>` takes. */
4
+ function Textarea(props) {
5
+ const made = controller(createAutosize, () => ({ value: props.value }));
6
+ return <Part of={made.textarea} tag="textarea" {...props}/>;
7
+ }
8
+ export const Autosize = { Textarea };
package/src/avatar.jsx CHANGED
@@ -11,7 +11,7 @@ function useAvatar() {
11
11
  function Root(props) {
12
12
  const made = controller(createAvatar, () => ({}));
13
13
  return (<Context.Provider value={made}>
14
- <Part part={made.root} tag="span" {...props}/>
14
+ <Part of={made.root} tag="span" {...props}/>
15
15
  </Context.Provider>);
16
16
  }
17
17
  /** The picture: in the page once `src` has loaded. */
@@ -21,7 +21,7 @@ function Image(props) {
21
21
  createComputed(() => made.source.set(local.src));
22
22
  const status = fromSignal(made.status);
23
23
  return (<Show when={status() === "loaded"}>
24
- <Part part={made.image} tag="img" {...rest}/>
24
+ <Part of={made.image} tag="img" {...rest}/>
25
25
  </Show>);
26
26
  }
27
27
  /** What shows until the picture has loaded, or when it cannot. */
@@ -29,7 +29,7 @@ function Fallback(props) {
29
29
  const made = useAvatar();
30
30
  const status = fromSignal(made.status);
31
31
  return (<Show when={status() !== "loaded"}>
32
- <Part part={made.fallback} tag="span" {...props}/>
32
+ <Part of={made.fallback} tag="span" {...props}/>
33
33
  </Show>);
34
34
  }
35
35
  export const Avatar = { Root, Image, Fallback };
package/src/button.jsx CHANGED
@@ -5,5 +5,5 @@ import { Part, controller } from "./runtime.jsx";
5
5
  export function Button(props) {
6
6
  const [local, rest] = splitProps(props, ["disabled", "focusableWhenDisabled", "nativeButton"]);
7
7
  const made = controller(createButton, () => ({ ...local }));
8
- return <Part part={made.root} tag="button" {...rest}/>;
8
+ return <Part of={made.root} tag="button" {...rest}/>;
9
9
  }