@cobdfamily/clf-core 7.0.1

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 (44) hide show
  1. package/README.md +250 -0
  2. package/dist/_variables.scss +973 -0
  3. package/dist/components/cobd-embed.d.ts +4 -0
  4. package/dist/components/cobd-embed.js +163 -0
  5. package/dist/components/cobd-nav.d.ts +1 -0
  6. package/dist/components/cobd-nav.js +383 -0
  7. package/dist/components/cobd-support.d.ts +26 -0
  8. package/dist/components/cobd-support.js +296 -0
  9. package/dist/components/font-scale-toggle.d.ts +9 -0
  10. package/dist/components/font-scale-toggle.js +159 -0
  11. package/dist/components/forms/checkbox.d.ts +1 -0
  12. package/dist/components/forms/checkbox.js +118 -0
  13. package/dist/components/forms/common.d.ts +17 -0
  14. package/dist/components/forms/common.js +137 -0
  15. package/dist/components/forms/index.d.ts +5 -0
  16. package/dist/components/forms/index.js +13 -0
  17. package/dist/components/forms/select.d.ts +1 -0
  18. package/dist/components/forms/select.js +132 -0
  19. package/dist/components/forms/submit.d.ts +1 -0
  20. package/dist/components/forms/submit.js +78 -0
  21. package/dist/components/forms/textarea.d.ts +1 -0
  22. package/dist/components/forms/textarea.js +95 -0
  23. package/dist/components/forms/textfield.d.ts +1 -0
  24. package/dist/components/forms/textfield.js +125 -0
  25. package/dist/components/index.d.ts +7 -0
  26. package/dist/components/index.js +33 -0
  27. package/dist/components/theme-toggle.d.ts +10 -0
  28. package/dist/components/theme-toggle.js +130 -0
  29. package/dist/i18n/chrome.json +94 -0
  30. package/dist/navs/cobd.ca.json +83 -0
  31. package/dist/navs/more-cobd.json +60 -0
  32. package/dist/navs.d.ts +27 -0
  33. package/dist/navs.js +193 -0
  34. package/dist/theming/font-scale-paint.d.ts +0 -0
  35. package/dist/theming/font-scale-paint.js +32 -0
  36. package/dist/theming/init.d.ts +1 -0
  37. package/dist/theming/init.js +19 -0
  38. package/dist/theming/runtime.d.ts +22 -0
  39. package/dist/theming/runtime.js +333 -0
  40. package/dist/tokens.css +972 -0
  41. package/dist/tokens.json +97 -0
  42. package/dist/tokens.scss +95 -0
  43. package/package.json +123 -0
  44. package/src/navs/schema.json +64 -0
package/README.md ADDED
@@ -0,0 +1,250 @@
1
+ # @cobdfamily/clf-core
2
+
3
+ Common Look and Feel toolkit for Bowen Community,
4
+ BlindHub, and COBD apps. One design-token source
5
+ feeds every consumer: Ionic apps, WordPress themes,
6
+ Keycloak login pages, Hugo sites, Moodle themes,
7
+ CiviCRM Standalone, and Capacitor-wrapped iframe
8
+ shells.
9
+
10
+ What ships:
11
+
12
+ - **Tokens** for colour / spacing / typography /
13
+ radii / shadows / motion, in CSS / SCSS / JSON.
14
+ - **Theming runtime** for light / dark / hc-light /
15
+ hc-dark + a three-step font-size scale.
16
+ - **Custom elements** -- all Light-DOM, all
17
+ auto-detect Ionic, all framework-neutral:
18
+ - `<cobd-theme-toggle>`
19
+ - `<cobd-font-scale-toggle>`
20
+ - `<cobd-nav>` (renders a COBD nav)
21
+ - `<cobd-textfield>` `<cobd-textarea>`
22
+ `<cobd-select>` `<cobd-checkbox>`
23
+ `<cobd-submit>` (form elements,
24
+ Form-Associated via ElementInternals)
25
+ - **Nav metadata** (the cobd.ca + more-cobd navs
26
+ as JSON) + the `getNav()` runtime accessor.
27
+ - **Chrome i18n strings** the engines + clf-factory
28
+ build pipeline consume.
29
+
30
+ For maintainers: see `HOW-IT-WORKS.md`.
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ npm install @cobdfamily/clf-core
36
+ ```
37
+
38
+ ## Quick start
39
+
40
+ For any consumer that wants CSS variables (works
41
+ in every build setup, no Sass needed):
42
+
43
+ ```css
44
+ @import url("https://cdn.blindhub.ca/clf-core/<version>/tokens.css");
45
+ ```
46
+
47
+ Or via the npm package:
48
+
49
+ ```ts
50
+ import "@cobdfamily/clf-core/tokens.css";
51
+ ```
52
+
53
+ Then reference the custom properties anywhere in
54
+ your styles:
55
+
56
+ ```css
57
+ .button {
58
+ background: var(--cobd-color-primary);
59
+ color: var(--cobd-color-primary-contrast);
60
+ }
61
+ ```
62
+
63
+ ## Token exports
64
+
65
+ The same token set ships in three formats so each
66
+ consumer picks whatever fits its build:
67
+
68
+ | Path | What for |
69
+ |-------------------------------------|------------------------------------------------|
70
+ | `@cobdfamily/clf-core/tokens.css` | Plain CSS custom properties. **Recommended**. |
71
+ | `@cobdfamily/clf-core/tokens.scss` | SCSS `$cobd-...` variables. |
72
+ | `@cobdfamily/clf-core/tokens.json` | Flat JSON map. Useful for native apps + tooling. |
73
+
74
+ All come from the same `src/tokens/*.json` files
75
+ and stay in lockstep automatically.
76
+
77
+ WordPress block themes get the same palette via
78
+ `@cobdfamily/clf-factory`'s WP engine tarball
79
+ (`theme.json` is generated there from clf-core's
80
+ tokens at factory build time).
81
+
82
+ ## Theming runtime
83
+
84
+ Programmatic theme control (light / dark /
85
+ hc-light / hc-dark / auto) plus the toggle custom
86
+ element:
87
+
88
+ ```ts
89
+ import {
90
+ getThemes,
91
+ getThemePreference,
92
+ setTheme,
93
+ initTheming,
94
+ } from "@cobdfamily/clf-core/theming";
95
+
96
+ initTheming(); // call once at app boot
97
+ setTheme("dark"); // activate from code
98
+
99
+ // Or drop the toggle anywhere:
100
+ import "@cobdfamily/clf-core/components/theme-toggle";
101
+ ```
102
+
103
+ ```html
104
+ <cobd-theme-toggle></cobd-theme-toggle>
105
+ ```
106
+
107
+ The runtime writes a `data-theme` attribute on
108
+ `<html>` (or removes it for `auto`); the CSS in
109
+ `tokens.css` honours both `data-theme` and
110
+ `prefers-color-scheme`. No framework dependency.
111
+
112
+ Text-size scale comes with its own toggle:
113
+
114
+ ```ts
115
+ import "@cobdfamily/clf-core/components/font-scale-toggle";
116
+ ```
117
+
118
+ ```html
119
+ <cobd-font-scale-toggle aria-label="Text size"></cobd-font-scale-toggle>
120
+ ```
121
+
122
+ A small pre-paint helper applies the persisted
123
+ scale before first paint so consumers don't get
124
+ a flash of medium-sized text:
125
+
126
+ ```html
127
+ <script src="https://cdn.blindhub.ca/clf-core/<ver>/theming/font-scale-paint.js"></script>
128
+ ```
129
+
130
+ (Classic blocking script; pair with the toggle's
131
+ `data-cobd-font-scale` cookie.)
132
+
133
+ ## Nav metadata + `<cobd-nav>`
134
+
135
+ The shared navs (cobd.ca, more-cobd) ship as data,
136
+ plus a custom element that renders them. Three
137
+ usage shapes:
138
+
139
+ ```ts
140
+ // Programmatic access (any framework):
141
+ import { getNav } from "@cobdfamily/clf-core/navs";
142
+ const nav = getNav("cobd.ca");
143
+
144
+ // Drop-in element:
145
+ import "@cobdfamily/clf-core/components/cobd-nav";
146
+ ```
147
+
148
+ ```html
149
+ <cobd-nav path="cobd.ca" aria-label="Primary"></cobd-nav>
150
+ ```
151
+
152
+ `path` accepts:
153
+
154
+ - a bundled slug (`"cobd.ca"` or `"more-cobd"`)
155
+ - a full URL (`"https://cobd.ca/wp-json/clf/v/menu"`)
156
+ to fetch live
157
+ - the sentinel `"local"` -- the element parses its
158
+ own `<ul>/<li>` children as the nav source
159
+ (useful when the host already renders the nav
160
+ for SEO / noscript)
161
+
162
+ Render shape depends on Ionic presence:
163
+ `<ion-list>` of `<ion-item>`s if Ionic is on the
164
+ page, plain `<ul>` of `<li><a>`s otherwise.
165
+
166
+ Each bundled nav is a JSON file under `src/navs/`.
167
+ Schema: `@cobdfamily/clf-core/schema/nav.json`.
168
+ Adding a new bundled nav: drop a JSON file in
169
+ `src/navs/`, rebuild, republish.
170
+
171
+ ## Form elements
172
+
173
+ Five Form-Associated custom elements wrap the
174
+ common field types. All accept attribute-only
175
+ configuration; all auto-detect Ionic (emit
176
+ `<ion-input>` / `<ion-select>` / etc. when on
177
+ the page, plain HTML when not); all participate
178
+ in `<form>` POST natively via `ElementInternals`.
179
+
180
+ ```html
181
+ <form method="post" action="/save">
182
+ <cobd-textfield
183
+ name="email" type="email" label="Email"
184
+ placeholder="you@example.com"
185
+ help="We only use this to contact you."
186
+ required></cobd-textfield>
187
+
188
+ <cobd-textarea
189
+ name="bio" label="About you" rows="4">
190
+ </cobd-textarea>
191
+
192
+ <cobd-select name="city" label="City">
193
+ <option value="van">Vancouver</option>
194
+ <option value="vic">Victoria</option>
195
+ </cobd-select>
196
+
197
+ <cobd-checkbox
198
+ name="opt_in" label="Send me updates">
199
+ </cobd-checkbox>
200
+
201
+ <cobd-submit label="Save"></cobd-submit>
202
+ </form>
203
+ ```
204
+
205
+ ```ts
206
+ // Register all five at once:
207
+ import "@cobdfamily/clf-core/components/forms";
208
+
209
+ // Or tree-shake by importing individually:
210
+ import "@cobdfamily/clf-core/components/forms/textfield";
211
+ import "@cobdfamily/clf-core/components/forms/select";
212
+ ```
213
+
214
+ `<cobd-submit>` also accepts `action` and `method`
215
+ attrs -- when set, the element wraps itself in
216
+ its own `<form>`, so the button stands alone
217
+ without a surrounding form (useful for "post and
218
+ go" actions).
219
+
220
+ ## Publishing
221
+
222
+ Every push to `main` auto-publishes to npm via the
223
+ `Publish to npm` GitHub Action. The patch version
224
+ becomes the build timestamp so consumers can pin to
225
+ `latest` and pick up changes on the next install.
226
+ `NPM_TOKEN` secret on the repo enables it.
227
+
228
+ ## Apps using CLF today
229
+
230
+ - BowenCommunity/Ferry -- Ionic + Angular
231
+ - BowenCommunity/Lift -- Ionic + Angular
232
+ - BowenCommunity/Springboard -- Ionic + Angular
233
+ - cobd.ca -- WordPress (via clf-factory's
234
+ generated theme.json)
235
+ - florin -- Angular (via tokens.css)
236
+
237
+ To add a new consumer:
238
+ `npm install @cobdfamily/clf-core`, pick the
239
+ import line above that matches your stack, done.
240
+
241
+ For consumers that DON'T want to author HTML
242
+ themselves (CMS-driven sites, mobile shells), see
243
+ `@cobdfamily/clf-factory`: it compiles pre-baked
244
+ header / footer / error fragments for WordPress,
245
+ Hugo, Keycloak, Moodle, CiviCRM Standalone,
246
+ Oister (Capacitor iframe shell), and static HTML.
247
+
248
+ ## License
249
+
250
+ AGPL-3.0. See `LICENSE`.