Skip to content

Commit d0d5c41

Browse files
shahryarjbshahryarjb
authored
Merge pull request #461 from mishka-group/usage-rules
Add Usage rules for all components and JS Hooks
2 parents 8c39747 + 2a6ccf0 commit d0d5c41

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

83 files changed

+17960
-2
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- Add Components prefix name in CLI and config file [#454](https://github.com/mishka-group/mishka_chelekom/pull/454)
66
- Add Module prefix name in CLI and config file [#459](https://github.com/mishka-group/mishka_chelekom/pull/459)
77
- Add `--no-save` flag to control prefix config saving [#459](https://github.com/mishka-group/mishka_chelekom/pull/459)
8+
- Add Usage rules for all components and JS Hooks[#461](https://github.com/mishka-group/mishka_chelekom/pull/461)
89

910
### Refactors:
1011

‎mix.exs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
defmodule MishkaChelekom.MixProject do
22
use Mix.Project
33

4-
@version "0.0.9-alpha.4"
4+
@version "0.0.9-alpha.5"
55
@source_url "https://github.com/mishka-group/mishka_chelekom"
66

77
def project do
@@ -54,7 +54,7 @@ defmodule MishkaChelekom.MixProject do
5454
defp package() do
5555
[
5656
extra: %{igniter_only: ["dev"]},
57-
files: ~w(lib priv .formatter.exs mix.exs LICENSE README*),
57+
files: ~w(lib priv .formatter.exs mix.exs LICENSE README* usage-rules.md usage-rules),
5858
licenses: ["Apache-2.0"],
5959
maintainers: ["Shahryar Tavakkoli", "Mona Aghili", "Arian Alijani"],
6060
links: %{

‎usage-rules.md‎

Lines changed: 384 additions & 0 deletions
Large diffs are not rendered by default.

‎usage-rules/components/accordion.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Accordion Component
2+
3+
Collapsible sections component for organizing content into expandable panels with smooth animations.
4+
5+
**Documentation**: https://mishka.tools/chelekom/docs/accordion
6+
7+
> **For LLM Agents**: If you need more details, examples, or edge cases not covered here, fetch the full documentation from the URL above.
8+
9+
## Generate
10+
11+
```bash
12+
# Generate with all options
13+
mix mishka.ui.gen.component accordion
14+
15+
# Generate with specific options
16+
mix mishka.ui.gen.component accordion --variant default,outline --color primary,natural
17+
18+
# Generate with custom module name
19+
mix mishka.ui.gen.component accordion --module MyAppWeb.Components.CustomAccordion
20+
```
21+
22+
## Dependencies
23+
24+
| Type | Components |
25+
|------|------------|
26+
| **Necessary** | `icon` |
27+
| **Optional** | None |
28+
| **JavaScript** | `collapsible.js` |
29+
30+
## Attributes
31+
32+
| Attribute | Type | Default | Description |
33+
|-----------|------|---------|-------------|
34+
| `id` | `:string` | auto-generated | Unique identifier for the accordion |
35+
| `class` | `:any` | `nil` | Custom CSS class for additional styling |
36+
| `multiple` | `:boolean` | `false` | Allow multiple panels open simultaneously |
37+
| `collapsible` | `:boolean` | `true` | Allow all panels to be closed |
38+
| `duration` | `:integer` | `200` | Animation duration in milliseconds |
39+
| `keep_mounted` | `:boolean` | `false` | Keep content mounted after first open |
40+
| `server_events` | `:boolean` | `false` | Send open/close events to LiveView |
41+
| `event_handler` | `:string` | `nil` | Specify event handler for accordion events |
42+
| `initial_open` | `:list` | `[]` | List of initially open item IDs |
43+
| `variant` | `:string` | `"base"` | Visual style variant |
44+
| `color` | `:string` | `"natural"` | Color theme |
45+
| `size` | `:string` | `"medium"` | Overall size |
46+
| `rounded` | `:string` | `"medium"` | Border radius |
47+
| `border` | `:string` | `"extra_small"` | Border style |
48+
| `space` | `:string` | `"small"` | Space between separated items |
49+
| `media_size` | `:string` | `"small"` | Size of media elements like icons and images |
50+
| `padding` | `:string` | `"small"` | Padding for accordion items |
51+
| `chevron_icon` | `:string` | `"hero-chevron-down"` | Chevron icon |
52+
| `chevron_position` | `:string` | `"right"` | Chevron position (left/right) |
53+
| `left_chevron` | `:boolean` | `false` | Position chevron on the left |
54+
| `right_chevron` | `:boolean` | `false` | Position chevron on the right |
55+
| `hide_chevron` | `:boolean` | `false` | Hide the chevron icon |
56+
| `chevron_class` | `:string` | `nil` | Additional CSS classes for the chevron |
57+
58+
## Slots
59+
60+
### `item` Slot
61+
62+
| Attribute | Type | Required | Description |
63+
|-----------|------|----------|-------------|
64+
| `id` | `:string` | No | Unique identifier (auto-generated if not provided) |
65+
| `title` | `:string` | **Yes** | Title of the accordion item |
66+
| `description` | `:string` | No | Optional description/subtitle |
67+
| `icon` | `:string` | No | Optional icon name |
68+
| `icon_class` | `:string` | No | Additional CSS classes for the item icon |
69+
| `icon_wrapper_class` | `:string` | No | Additional CSS classes for the item icon wrapper |
70+
| `image` | `:string` | No | Optional image source URL |
71+
| `image_class` | `:string` | No | Additional CSS classes for the image |
72+
| `trigger_class` | `:string` | No | Additional CSS classes for the trigger |
73+
| `content_class` | `:string` | No | Additional CSS classes for the content |
74+
| `open` | `:boolean` | No | Whether this item should be initially open |
75+
76+
## Available Options
77+
78+
### Variants
79+
`base`, `base_separated`, `default`, `bordered`, `bordered_separated`, `outline`, `outline_separated`, `transparent`, `shadow`, `gradient`
80+
81+
### Colors
82+
`natural`, `white`, `dark`, `primary`, `secondary`, `success`, `warning`, `danger`, `info`, `silver`, `misc`, `dawn`
83+
84+
### Sizes
85+
`extra_small`, `small`, `medium`, `large`, `extra_large`
86+
87+
### Rounded
88+
`extra_small`, `small`, `medium`, `large`, `extra_large`, `full`, `none`
89+
90+
### Padding
91+
`extra_small`, `small`, `medium`, `large`, `extra_large`
92+
93+
### Space
94+
`extra_small`, `small`, `medium`, `large`, `extra_large`, `none`
95+
96+
## Usage Examples
97+
98+
### Basic Usage
99+
100+
```heex
101+
<.accordion>
102+
<:item title="Section 1">
103+
Content for section 1
104+
</:item>
105+
<:item title="Section 2">
106+
Content for section 2
107+
</:item>
108+
</.accordion>
109+
```
110+
111+
### With Colors and Variants
112+
113+
```heex
114+
<.accordion variant="outline" color="primary" rounded="large">
115+
<:item title="Primary Outline" description="With description">
116+
This is an outlined accordion with primary color.
117+
</:item>
118+
</.accordion>
119+
```
120+
121+
### Multiple Open Panels
122+
123+
```heex
124+
<.accordion multiple={true}>
125+
<:item title="Panel 1" open={true}>
126+
Initially open panel
127+
</:item>
128+
<:item title="Panel 2">
129+
Closed by default
130+
</:item>
131+
</.accordion>
132+
```
133+
134+
### With Icons and Images
135+
136+
```heex
137+
<.accordion>
138+
<:item title="Settings" icon="hero-cog-6-tooth">
139+
Settings content here
140+
</:item>
141+
<:item title="Profile" image="/images/avatar.png">
142+
Profile content here
143+
</:item>
144+
</.accordion>
145+
```
146+
147+
### Server Events Integration
148+
149+
```heex
150+
<.accordion server_events={true} event_handler="handle_accordion">
151+
<:item id="item-1" title="Tracked Panel">
152+
This panel sends events to LiveView
153+
</:item>
154+
</.accordion>
155+
```
156+
157+
Handle events in your LiveView:
158+
159+
```elixir
160+
def handle_event("collapsible_open", %{"id" => id}, socket) do
161+
# Handle panel open
162+
{:noreply, socket}
163+
end
164+
165+
def handle_event("collapsible_close", %{"id" => id}, socket) do
166+
# Handle panel close
167+
{:noreply, socket}
168+
end
169+
```
170+
171+
### Initial Open Items
172+
173+
```heex
174+
<.accordion initial_open={["section-1", "section-3"]}>
175+
<:item id="section-1" title="Section 1">Open by default</:item>
176+
<:item id="section-2" title="Section 2">Closed</:item>
177+
<:item id="section-3" title="Section 3">Open by default</:item>
178+
</.accordion>
179+
```
180+
181+
### Separated Variant with Space
182+
183+
```heex
184+
<.accordion variant="bordered_separated" space="medium" rounded="large">
185+
<:item title="Card 1">Content 1</:item>
186+
<:item title="Card 2">Content 2</:item>
187+
</.accordion>
188+
```
189+
190+
### Custom Chevron
191+
192+
```heex
193+
<.accordion
194+
chevron_icon="hero-plus"
195+
chevron_position="left"
196+
chevron_class="text-primary-500"
197+
>
198+
<:item title="Custom Chevron">
199+
Content with custom chevron on the left
200+
</:item>
201+
</.accordion>
202+
```
203+
204+
### Hidden Chevron
205+
206+
```heex
207+
<.accordion hide_chevron={true}>
208+
<:item title="No Chevron">
209+
Accordion without chevron indicator
210+
</:item>
211+
</.accordion>
212+
```
213+
214+
## JavaScript Hook
215+
216+
The accordion uses the `Collapsible` JavaScript hook for animations. This is automatically configured when you generate the component.
217+
218+
The hook is registered in `assets/js/app.js`:
219+
220+
```javascript
221+
import MishkaComponents from "../vendor/mishka_components.js";
222+
223+
let liveSocket = new LiveSocket("/live", Socket, {
224+
hooks: { ...MishkaComponents }
225+
});
226+
```
227+
228+
## Accessibility
229+
230+
- WAI-ARIA compliant with proper `aria-expanded` attributes
231+
- Keyboard navigation support
232+
- Screen reader friendly
233+
- Focus management for opened/closed states

0 commit comments

Comments
 (0)