@loomidev/bottom-nav 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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Michael K. Ocansey
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,245 @@
1
+ # @loomidev/bottom-nav
2
+
3
+ `<loomi-bottom-nav>` and `<loomi-bottom-nav-item>` — a mobile bottom navigation bar with
4
+ icons, labels, badges, eight active-state styles, and a routing-agnostic click event so
5
+ any router (or plain `<a>` links) can drive it.
6
+
7
+ ```bash
8
+ npm install @loomidev/bottom-nav lit
9
+ ```
10
+
11
+ ```js
12
+ import "@loomidev/bottom-nav";
13
+ ```
14
+
15
+ ```html
16
+ <loomi-bottom-nav active="home" active-style="pill">
17
+ <loomi-bottom-nav-item name="home" icon="home" href="/home">Home</loomi-bottom-nav-item>
18
+ <loomi-bottom-nav-item name="orders" icon="archive-box" href="/orders">Orders</loomi-bottom-nav-item>
19
+ <loomi-bottom-nav-item name="profile" icon="user" href="/profile">Profile</loomi-bottom-nav-item>
20
+ </loomi-bottom-nav>
21
+ ```
22
+
23
+ ## Safe areas
24
+
25
+ The bar's own bottom padding (or, in `floating` mode, its distance from the viewport edge)
26
+ accounts for `env(safe-area-inset-bottom)`, so it clears the home indicator on notched
27
+ phones automatically — no extra configuration needed.
28
+
29
+ ## Flexible navigation
30
+
31
+ Each item decides how it navigates from the attributes you give it:
32
+
33
+ - **`href` set** → renders a real `<a>`. Native/SPA-router links, Laravel routes, anchors —
34
+ all just work, including `target="_blank"` (always preserved — never intercepted).
35
+ - **`href` omitted** → renders a `<button>`. Use this when a JS router owns navigation
36
+ entirely; the item still needs a `value` (or `name`) to identify itself.
37
+ - **Either way**, clicking always fires `loomi-change` on the parent, so a client-side
38
+ router can take over. Add `prevent-default` to always suppress the real anchor
39
+ navigation (letting your router fully own it), or call `event.preventDefault()` inside
40
+ your own `loomi-change` listener to suppress it dynamically, per click.
41
+
42
+ ```js
43
+ document.querySelector("loomi-bottom-nav").addEventListener("loomi-change", (event) => {
44
+ const { item, value } = event.detail;
45
+ router.push(`/app/${value}`);
46
+ });
47
+ ```
48
+
49
+ ```html
50
+ <loomi-bottom-nav-item value="orders" href="/orders" prevent-default>Orders</loomi-bottom-nav-item>
51
+ ```
52
+
53
+ `active` on the parent is the controlled identifier — set it from your router (e.g. on
54
+ every route change) and the matching item recomputes its active state. Clicking an
55
+ (enabled) item also updates `active` locally first, for immediate visual feedback, before
56
+ `loomi-change` reaches your listener.
57
+
58
+ ## Active styles
59
+
60
+ `active-style` on `<loomi-bottom-nav>` picks the active item's visual treatment:
61
+ `pill` (default) · `underline` · `top-line` · `background` · `icon-only` · `dot` ·
62
+ `border` · `minimal`.
63
+
64
+ ```html
65
+ <loomi-bottom-nav active="cart" active-style="dot">
66
+ <loomi-bottom-nav-item name="home" icon="home">Home</loomi-bottom-nav-item>
67
+ <loomi-bottom-nav-item name="cart" icon="shopping-cart" badge="3">Cart</loomi-bottom-nav-item>
68
+ <loomi-bottom-nav-item name="account" icon="user">Account</loomi-bottom-nav-item>
69
+ </loomi-bottom-nav>
70
+ ```
71
+
72
+ - `pill` / `background` / `border` fill or outline the whole link surface.
73
+ - `icon-only` recolors just the icon, leaving the label its normal muted color.
74
+ - `minimal` recolors both icon and label with no background/border/line.
75
+ - `underline` / `top-line` / `dot` add a small accent marker at the link's bottom/top edge
76
+ or below the icon, in addition to recoloring icon + label.
77
+
78
+ ## Badges
79
+
80
+ Set `badge` on any item for a small count/label pill anchored to its icon:
81
+
82
+ ```html
83
+ <loomi-bottom-nav-item name="cart" icon="shopping-cart" badge="3">Cart</loomi-bottom-nav-item>
84
+ ```
85
+
86
+ ## Variant: floating
87
+
88
+ ```html
89
+ <loomi-bottom-nav active="cart" variant="floating" active-style="pill">
90
+ <loomi-bottom-nav-item name="home" icon="home">Home</loomi-bottom-nav-item>
91
+ <loomi-bottom-nav-item name="cart" icon="shopping-cart" badge="3">Cart</loomi-bottom-nav-item>
92
+ <loomi-bottom-nav-item name="account" icon="user">Account</loomi-bottom-nav-item>
93
+ </loomi-bottom-nav>
94
+ ```
95
+
96
+ `variant="floating"` detaches the bar from the viewport edge into a rounded, elevated,
97
+ inset island instead of an edge-to-edge dock.
98
+
99
+ ## Icons
100
+
101
+ Icons render through `<loomi-icon>`. Set `icon-source` on the parent to change the icon
102
+ set for every item at once, or on an individual `<loomi-bottom-nav-item>` to override just
103
+ that one:
104
+
105
+ ```html
106
+ <loomi-bottom-nav icon-source="iconsax" active="home">
107
+ <loomi-bottom-nav-item name="home" icon="home-2">Home</loomi-bottom-nav-item>
108
+ <loomi-bottom-nav-item name="star" icon="star" icon-source="heroicons">Star</loomi-bottom-nav-item>
109
+ </loomi-bottom-nav>
110
+ ```
111
+
112
+ ## Colors and disabled state
113
+
114
+ ```html
115
+ <loomi-bottom-nav color="success" active="home">
116
+ <loomi-bottom-nav-item name="home" icon="home">Home</loomi-bottom-nav-item>
117
+ <loomi-bottom-nav-item name="orders" icon="archive-box" disabled>Orders</loomi-bottom-nav-item>
118
+ </loomi-bottom-nav>
119
+ ```
120
+
121
+ ## Accessibility
122
+
123
+ `<loomi-bottom-nav>` renders a real `<nav>` landmark (`label` sets its `aria-label`,
124
+ default `"Primary"`). Each item renders a real `<a>` (when `href` is set) or `<button>` —
125
+ never a clickable `<div>` — so screen readers and keyboard users get native semantics for
126
+ free. The active item gets `aria-current="page"`.
127
+
128
+ - `Tab` / `Shift+Tab` reach every item in document order, like any row of links/buttons.
129
+ - `←`/`→` (or `↑`/`↓`) move focus between items without navigating — manual activation,
130
+ per the WAI-ARIA APG toolbar pattern, so arrowing through never triggers a page navigation
131
+ by accident. `Home`/`End` jump to the first/last enabled item. `Enter`/`Space` (or a
132
+ click) activate the focused item natively.
133
+ - Disabled items (`disabled`) are skipped by arrow-key roving focus and excluded from the
134
+ tab order (`tabindex="-1"` for links, native `disabled` for buttons).
135
+ - Focus is visible via `:focus-visible`, ringed with the component's accent color.
136
+
137
+ For the library-wide baseline, see [Foundations — Accessibility](https://loomiui.com/foundations/#accessibility).
138
+
139
+ ## Responsive behavior
140
+
141
+ Designed for mobile: `<loomi-bottom-nav>` docks itself with `position: fixed` at the
142
+ viewport bottom (or floats, see `variant` below) so you don't need any wrapping layout.
143
+ Set `mobile-only` to hide it automatically at tablet width and up (768px), the common
144
+ pattern where a sidebar or top nav takes over on larger screens. Items share the available
145
+ width equally (`flex: 1`) and truncate long labels rather than wrapping — designed for
146
+ 3–5 items.
147
+
148
+ For the shared container and viewport rules, see [Foundations — Responsive behavior](https://loomiui.com/foundations/#responsive-behavior).
149
+
150
+ ## Dark mode
151
+
152
+ Uses semantic `--loomi-surface` / `--loomi-surface-border` / `--loomi-text-muted` tokens
153
+ for the bar background, divider, and inactive icon/label color, so it flips automatically
154
+ with `.dark` on `<html>` (via `@loomidev/theme-switcher` or your own theme toggle). The
155
+ active-state tokens (see **Styling hooks** below) default to the instance's `color`
156
+ accent, which is also dark-mode aware.
157
+
158
+ For theme activation, token overrides, and contrast guidance, see [Foundations — Dark mode](https://loomiui.com/foundations/#dark-mode).
159
+
160
+ ## Attributes — `<loomi-bottom-nav>`
161
+
162
+ | Attribute | Default | Description |
163
+ | -------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
164
+ | `active` | _(blank)_ | The active item's `value`/`name`. Controlled — set it from your router. |
165
+ | `active-style` | `pill` | `pill` \| `underline` \| `top-line` \| `background` \| `icon-only` \| `dot` \| `border` \| `minimal`. |
166
+ | `variant` | `fixed` | `fixed` (edge-to-edge dock) \| `floating` (rounded, elevated island). |
167
+ | `color` | `primary` | Accent for the active item's color/background/border/dot. Any loomi color. |
168
+ | `icon-source` | `heroicons` | Default icon set for every item — see `<loomi-icon>`'s `source`. |
169
+ | `label` | `Primary` | `aria-label` for the `<nav>` landmark. |
170
+ | `mobile-only` | `false` | Hides the bar at 768px and up. _(boolean)_ |
171
+
172
+ ## Attributes — `<loomi-bottom-nav-item>`
173
+
174
+ | Attribute | Default | Description |
175
+ | ----------------- | --------- | --------------------------------------------------------------------------------------------- |
176
+ | `label` | _(blank)_ | Label text. Falls back to slotted text if empty. |
177
+ | `icon` | _(blank)_ | Built-in icon name. |
178
+ | `icon-source` | _(blank)_ | Per-item icon set override. Empty = inherit from the parent. |
179
+ | `badge` | _(blank)_ | Count/label shown as a small pill on the icon. Empty = no badge. |
180
+ | `disabled` | `false` | Blocks navigation, clicks, and arrow-key focus. _(boolean)_ |
181
+ | `value` | _(blank)_ | Identifier matched against the parent's `active`. Falls back to `name`, then slot text. |
182
+ | `href` | _(blank)_ | Renders a real `<a>` instead of a `<button>`. |
183
+ | `target` | _(blank)_ | Anchor `target`. `_blank` always keeps native new-tab behavior. |
184
+ | `rel` | _(blank)_ | Anchor `rel`. Defaults to `noopener noreferrer` when `target="_blank"`. |
185
+ | `prevent-default` | `false` | Always suppress real navigation, even with `href` set. _(boolean)_ |
186
+ | `active` | `false` | Normally set by the parent. Set directly only when using this element standalone. _(boolean)_ |
187
+
188
+ ## Slots
189
+
190
+ | Slot | Description |
191
+ | ----------- | ------------------------------------ |
192
+ | _(default)_ | Content placed inside the component. |
193
+
194
+ ## Events
195
+
196
+ | Event | Detail |
197
+ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
198
+ | `loomi-change` | `{ item, value, name, href }`. Fired by the clicked item, bubbles through the parent. Cancelable — `event.preventDefault()` suppresses real anchor navigation for that click. |
199
+
200
+ ## Parts
201
+
202
+ | Part | Element |
203
+ | ------------------ | --------------------------------------------------------------------------- |
204
+ | `nav` | The `<loomi-bottom-nav>`'s internal `<nav>`. |
205
+ | `link` | The item's underlying `<a>`/`<button>`. |
206
+ | `icon` | The item's `<loomi-icon>`. |
207
+ | `label` | The item's label wrapper. |
208
+ | `badge` | The badge pill (only rendered when `badge` is set). |
209
+ | `active-indicator` | The underline/top-line/dot marker (only visible for those `active-style`s). |
210
+
211
+ ```css
212
+ loomi-bottom-nav-item::part(link) { }
213
+ loomi-bottom-nav-item::part(icon) { }
214
+ loomi-bottom-nav-item::part(label) { }
215
+ loomi-bottom-nav-item::part(badge) { }
216
+ loomi-bottom-nav-item::part(active-indicator) { }
217
+ ```
218
+
219
+ ## Styling hooks
220
+
221
+ | Variable | Default |
222
+ | ------------------------------------ | ------------------------------------- |
223
+ | `--loomi-bottom-nav-active-bg` | the `color` accent's soft tint |
224
+ | `--loomi-bottom-nav-active-color` | the `color` accent's foreground shade |
225
+ | `--loomi-bottom-nav-active-border` | the `color` accent |
226
+ | `--loomi-bottom-nav-active-radius` | `999px` |
227
+ | `--loomi-bottom-nav-active-dot-size` | `6px` |
228
+ | `--loomi-bottom-nav-badge-bg` | `var(--loomi-error-600)` |
229
+ | `--loomi-bottom-nav-badge-color` | `var(--loomi-white)` |
230
+
231
+ ```css
232
+ loomi-bottom-nav {
233
+ --loomi-bottom-nav-active-bg: var(--loomi-primary-100);
234
+ --loomi-bottom-nav-active-color: var(--loomi-primary-700);
235
+ --loomi-bottom-nav-active-border: var(--loomi-primary-600);
236
+ --loomi-bottom-nav-active-radius: 999px;
237
+ --loomi-bottom-nav-active-dot-size: 6px;
238
+ }
239
+ ```
240
+
241
+ ## Dependencies
242
+
243
+ - `@loomidev/core`
244
+ - `@loomidev/icon`
245
+ - `@loomidev/icons`