@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 +21 -0
- package/README.md +245 -0
- package/custom-elements.json +666 -0
- package/dist/generated/styles.css.d.ts +3 -0
- package/dist/generated/styles.css.d.ts.map +1 -0
- package/dist/generated/styles.css.js +5 -0
- package/dist/generated/styles.css.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -0
- package/dist/loomi-bottom-nav.d.ts +123 -0
- package/dist/loomi-bottom-nav.d.ts.map +1 -0
- package/dist/loomi-bottom-nav.js +339 -0
- package/dist/loomi-bottom-nav.js.map +1 -0
- package/package.json +62 -0
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`
|