diff --git a/app/Http/Controllers/ShowDocumentationController.php b/app/Http/Controllers/ShowDocumentationController.php index 99166c45..33cc7c42 100644 --- a/app/Http/Controllers/ShowDocumentationController.php +++ b/app/Http/Controllers/ShowDocumentationController.php @@ -10,6 +10,7 @@ use Illuminate\Http\RedirectResponse; use Illuminate\Http\Request; use Illuminate\Support\Arr; +use Illuminate\Support\Facades\Blade; use Illuminate\Support\Facades\Cache; use Illuminate\Support\Str; use Illuminate\View\View; @@ -116,9 +117,18 @@ protected function getPageProperties($platform, $version, $page = null): array $pageProperties['tableOfContents'] = $this->extractTableOfContents($pageProperties['content']); $navigation = $this->getNavigation($platform, $version); - $pageProperties['navigation'] = Menu::build($navigation, function (Menu $menu, $nav): void { + + $superNativeBadge = Blade::render( + '' + ); + + $label = fn (array $node): string => ($node['super_native'] ?? false) + ? $node['title'].$superNativeBadge + : $node['title']; + + $pageProperties['navigation'] = Menu::build($navigation, function (Menu $menu, $nav) use ($label): void { if (array_key_exists('path', $nav)) { - $menu->link($nav['path'], $nav['title']); + $menu->link($nav['path'], $label($nav)); } elseif (array_key_exists('children', $nav)) { $menu->setItemParentAttribute('x-data', '{ open: $el.classList.contains(\'active\') }'); @@ -168,14 +178,14 @@ protected function getPageProperties($platform, $version, $page = null): array ]); foreach ($child['children'] as $subChild) { - $subSubmenu->link($subChild['path'], $subChild['title']); + $subSubmenu->link($subChild['path'], $label($subChild)); } $subSubmenu->append(''); $submenu->submenu($subHeader, $subSubmenu); } else { - $submenu->link($child['path'], $child['title']); + $submenu->link($child['path'], $label($child)); } } @@ -249,6 +259,7 @@ protected function getNavigation(string $platform, string $version): array 'path' => $path, 'title' => $parsedSection->matter('title', ''), 'order' => $parsedSection->matter('order', 0), + 'super_native' => (bool) $parsedSection->matter('super_native', false), ]); } @@ -288,6 +299,7 @@ protected function getNavigation(string $platform, string $version): array 'path' => $path, 'title' => $title, 'order' => $parsedSection->matter('order', 0), + 'super_native' => (bool) $parsedSection->matter('super_native', false), ]); } @@ -335,6 +347,7 @@ protected function getNavigation(string $platform, string $version): array 'path' => $path, 'title' => $title, 'order' => $parsedPage->matter('order', 0), + 'super_native' => (bool) $parsedPage->matter('super_native', false), ]); } diff --git a/resources/views/components/docs/super-native-beta.blade.php b/resources/views/components/docs/super-native-beta.blade.php new file mode 100644 index 00000000..0ff082ed --- /dev/null +++ b/resources/views/components/docs/super-native-beta.blade.php @@ -0,0 +1,7 @@ +
+ +
+

This is a Super Native feature — currently in beta

+

{{ $slot->isEmpty() ? 'Super Native is still in beta, so its APIs and behaviour may change before a stable release.' : $slot }}

+
+
diff --git a/resources/views/components/icons/super-native.blade.php b/resources/views/components/icons/super-native.blade.php new file mode 100644 index 00000000..8dc6b882 --- /dev/null +++ b/resources/views/components/icons/super-native.blade.php @@ -0,0 +1,14 @@ +merge(['class' => 'lucide lucide-super-native']) }} + xmlns="http://www.w3.org/2000/svg" + width="24" + height="24" + viewBox="0 0 24 24" + fill="none" + stroke="currentColor" + stroke-width="1.5" + stroke-linecap="round" + stroke-linejoin="round" +> + + diff --git a/resources/views/docs/mobile/3/edge-components/_index.md b/resources/views/docs/mobile/3/edge-components/_index.md index e5f3a985..d0e24109 100644 --- a/resources/views/docs/mobile/3/edge-components/_index.md +++ b/resources/views/docs/mobile/3/edge-components/_index.md @@ -1,4 +1,4 @@ --- title: EDGE Components -order: 30 +order: 50 --- diff --git a/resources/views/docs/mobile/3/edge-components/activity-indicator.md b/resources/views/docs/mobile/3/edge-components/activity-indicator.md new file mode 100644 index 00000000..edaffbbe --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/activity-indicator.md @@ -0,0 +1,84 @@ +--- +title: Activity Indicator +order: 350 +super_native: true +--- + + + +## Overview + +A circular spinner indicating background activity. Always indeterminate — for determinate progress use +[``](progress-bar). Renders as a SwiftUI `ProgressView` on iOS and Material3 +`CircularProgressIndicator` on Android. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported, plus: + +- `size` - `"sm"`, `"md"` (default), or `"lg"` (optional, string). Legacy ints `1`=large, `2`=small are also accepted +- `color` - Spinner color as hex string (optional). Leave unset to use `theme.primary` +- `a11y-label` - Accessibility label (optional) + + + +## Examples + +### Centered loading screen + +@verbatim +```blade + + + Loading... + +``` +@endverbatim + +### Inline loading + +@verbatim +```blade + + + Refreshing + +``` +@endverbatim + +### Override the tint + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\ActivityIndicator; + +ActivityIndicator::make() + ->size('lg') + ->color('#7C3AED') + ->a11yLabel('Loading messages'); +``` + +- `make()` - Create a new indicator +- `size(string|int $size)` - `"sm" | "md" | "lg"`. Legacy: `1`=large, `2`=small +- `color(string $hex)` - Override the theme tint +- `a11yLabel(string $value)` - Accessibility label diff --git a/resources/views/docs/mobile/3/edge-components/badge.md b/resources/views/docs/mobile/3/edge-components/badge.md new file mode 100644 index 00000000..9abc4451 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/badge.md @@ -0,0 +1,93 @@ +--- +title: Badge +order: 360 +super_native: true +--- + + + +## Overview + +A small count or text marker, typically used as an overlay on nav items, list rows, or buttons. Renders as a capsule +pill. + +Per Model 3, colors come from the theme via the semantic `variant` prop — there are no per-instance overrides. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +- `count` - Numeric count. Renders as `"99+"` for values above 99 (optional, int) +- `label` - Arbitrary short text. Wins over `count` when both are set (optional, string) +- `variant` - Color variant (optional, string, default: `destructive`): + - `destructive` — `theme.destructive` / `theme.onDestructive` + - `primary` — `theme.primary` / `theme.onPrimary` + - `accent` — `theme.accent` / `theme.onAccent` +- `a11y-label` - Accessibility label (optional) + + + +## Examples + +### Count badge + +@verbatim +```blade + + + + +``` +@endverbatim + +### Label badge + +@verbatim +```blade + +``` +@endverbatim + +### Anchored to an icon + +Use a [``](stack) to layer the badge over its target: + +@verbatim +```blade + + + + + + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Badge; + +Badge::make() + ->count(3) + ->variant('primary'); + +Badge::make() + ->label('New') + ->variant('accent'); +``` + +- `make()` - Create a badge +- `count(int $count)` - Numeric count (capped display at `99+`) +- `label(string $text)` - Short text label (wins over `count`) +- `variant(string $variant)` - `destructive | primary | accent` +- `a11yLabel(string $value)` - Accessibility label diff --git a/resources/views/docs/mobile/3/edge-components/bottom-nav.md b/resources/views/docs/mobile/3/edge-components/bottom-nav.md index ff047141..978505b8 100644 --- a/resources/views/docs/mobile/3/edge-components/bottom-nav.md +++ b/resources/views/docs/mobile/3/edge-components/bottom-nav.md @@ -40,28 +40,84 @@ A bottom navigation bar with up to 5 items. Used for your app's primary navigati - `label-visibility` - `labeled`, `selected`, or `unlabeled` (optional, default: `labeled`) - `dark` - Force dark mode styling (optional) +- `active-color` - Color of the active tab's icon and label. Hex string (optional) +- `background-color` - Bar background color. Hex string. Wins over `dark`'s default (optional) +- `text-color` - Color of inactive tab icons and labels. Hex string. Active tabs use `active-color` (optional) + + ## Children A `` can contain up to 5 `` elements. +### Props + - `id` - Unique identifier (required) - `icon` - A named [icon](icons) (required) - `label` - Accessibility label (required) - `url` - A URL to navigate to in the web view (required) - `active` - Highlight this item as active (optional, default: `false`) -- `badge` - Badge text/number (optional) -- `news` - Show "new" indicator dot (optional, default: `false`) +- `badge` - Badge text/number, e.g. `"2"` — small red pill anchored top-right of the icon (optional) +- `news` - Show a small red dot anchored top-right of the icon. Mutually exclusive with `badge` (optional, default: `false`) ### `badge` example +
![](/img/docs/edge-bottom-nav-item-badge.png)
+ +## Builder API + +When a `` is supplied by a [layout](../the-basics/layouts), you build it fluently with the `TabBar` +and `Tab` builders rather than writing it in Blade. + +```php +use Native\Mobile\Edge\Layouts\Builders\Tab; +use Native\Mobile\Edge\Layouts\Builders\TabBar; + +TabBar::make() + ->dark() + ->activeColor('#0891b2') + ->labelVisibility('labeled') + ->backgroundColor('#0F172A') + ->textColor('#94A3B8') + ->add(Tab::link('Chats', '/syncup', icon: 'chat_bubble')->badge('2')) + ->add(Tab::link('Friends', '/syncup/friends', icon: 'person.3.fill')->news()) + ->add(Tab::link('Profile', '/syncup/profile', icon: 'person')->active()); +``` + +### `TabBar` methods + +- `make()` - Create a new builder +- `dark(bool $dark = true)` - Force dark mode styling +- `activeColor(string $color)` - Color of the active tab's icon and label +- `backgroundColor(string $color)` - Bar background color (overrides `dark()`'s default) +- `textColor(string $color)` - Color of inactive tab icons and labels +- `labelVisibility(string $mode)` - `"labeled"`, `"selected"`, or `"unlabeled"` +- `add(Tab $tab)` - Append a tab item + +### `Tab` methods + +- `link(string $label, string $url, ?string $icon = null)` - Build a tab. The id defaults to the label slugified +- `id(string $id)` - Override the auto-generated id +- `icon(string $icon)` - A named [icon](icons) +- `badge(string $badge, ?string $color = null)` - Show a numeric/text badge +- `news(bool $news = true)` - Show a red dot indicator +- `active(bool $active = true)` - Mark this tab as active diff --git a/resources/views/docs/mobile/3/edge-components/bottom-sheet.md b/resources/views/docs/mobile/3/edge-components/bottom-sheet.md new file mode 100644 index 00000000..6f344215 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/bottom-sheet.md @@ -0,0 +1,132 @@ +--- +title: Bottom Sheet +order: 700 +super_native: true +--- + + + +## Overview + +A modal panel that slides up from the bottom of the screen. Use it for contextual actions, forms, and detail views +that overlay the main content. Renders as SwiftUI's `.sheet` with `presentationDetents` on iOS and a Material3 +`ModalBottomSheet` on Android. + +Per Model 3, the container color resolves from `theme.surface`. For a custom surface wrap content in a +``. + +@verbatim +```blade + + + Sheet Title + Sheet content goes here. + + + +``` +@endverbatim + +## Props + +- `visible` - Whether the sheet is shown (required, boolean) +- `detents` - Allowed sheet heights (optional, default: `"medium,large"`). Comma-separated combination of: + - `small` (25% of screen) + - `medium` + - `large` + - `full` (100% of screen) + - A numeric fraction `0.0`–`1.0` for a custom height (e.g. `"0.4"` for 40%) +- `a11y-label` - Accessibility label (optional) + +## Events + +- `@dismiss` - Livewire method called when the sheet is dismissed (swipe down or tap outside) + +## Children + +Accepts any EDGE elements as children. The children are rendered inside the sheet's content area. + +## Examples + +### Action sheet + +@verbatim +```blade + + + + + + Edit + + + + + + + Share + + + + + + + Delete + + + + +``` +@endverbatim + +### Form in a sheet + +@verbatim +```blade + + + Add Item + + + + + + + + +``` +@endverbatim + +### Custom height + +@verbatim +```blade + + + +``` +@endverbatim + + + +## Element + +```php +use Nativephp\NativeUi\Elements\BottomSheet; + +BottomSheet::make() + ->visible($showSheet) + ->detents('medium,large') + ->onDismiss('hideSheet'); +``` + +- `make()` - Create a bottom sheet +- `visible(bool $value = true)` - Toggle visibility +- `detents(string $detents)` - Allowed heights +- `a11yLabel(string $value)` - Accessibility label +- `onDismiss(string $method)` - Livewire method invoked on dismissal diff --git a/resources/views/docs/mobile/3/edge-components/button-group.md b/resources/views/docs/mobile/3/edge-components/button-group.md new file mode 100644 index 00000000..22c7e79b --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/button-group.md @@ -0,0 +1,86 @@ +--- +title: Button Group +order: 315 +super_native: true +--- + + + +## Overview + +A segmented single-choice selector. Each option is a pressable pill in a horizontal bar; the active one fills with +`theme.primary`. The group owns the selected-index state. + +Use this for short, mutually-exclusive choices that fit on one row. For more options or longer labels use a +[``](tab-row) or [``](select). + +@verbatim +```blade + +``` +@endverbatim + +## Props + +- `options` - Array of option labels (required, array of strings) +- `value` / `selected-index` - Currently selected index (optional, int, default: `0`) +- `disabled` - Disable the group (optional, boolean, default: `false`) +- `a11y-label` - Accessibility label (optional) + +## Events + +- `@change` - Livewire method called when the selection changes. Receives the new index as a parameter + +## Two-way Binding + +`native:model` binds the selected index to a Livewire integer property: + +@verbatim +```blade + +``` +@endverbatim + +## Examples + +### Period picker + +@verbatim +```blade + +``` +@endverbatim + +### With manual change handler + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\ButtonGroup; + +ButtonGroup::make() + ->options(['Daily', 'Weekly', 'Monthly']) + ->selectedIndex(1) + ->onChange('setPeriod'); +``` + +- `make()` - Create a button group +- `options(array $options)` - Option labels +- `selectedIndex(int $index)` - Currently selected index +- `disabled(bool $value = true)` - Disable the group +- `a11yLabel(string $value)` - Accessibility label +- `syncMode(string $mode)` - `live | blur | debounce` (set by `native:model` modifiers) +- `onChange(string $method)` - Livewire method invoked on change diff --git a/resources/views/docs/mobile/3/edge-components/button.md b/resources/views/docs/mobile/3/edge-components/button.md new file mode 100644 index 00000000..d4e97c21 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/button.md @@ -0,0 +1,131 @@ +--- +title: Button +order: 310 +super_native: true +--- + + + +## Overview + +A native button. Renders as a SwiftUI `Button` with `buttonStyle(...)` on iOS and a Material3 `Button` on Android. + +Visual styling follows Model 3 — colors, radius, shadow, and typography come from the theme. There are intentionally +**no per-instance** color, background, border, radius, shadow, font-size, or font-weight overrides. For full visual +control drop to a [``](pressable) wrapping your own content. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +The label can be passed as the `label` attribute or as slot content between the tags. If both are set, `label` wins. + +- `label` - Button text (optional if using slot content) +- `variant` - Semantic style: `primary` (default), `secondary`, `destructive`, `ghost` +- `size` - `sm`, `md` (default), `lg` +- `icon` - A leading [icon](icons) name (optional) +- `icon-trailing` - A trailing [icon](icons) name (optional) +- `disabled` - Disable the button (optional, boolean, default: `false`) +- `loading` - Show a spinner in place of the leading icon and prevent presses (optional, boolean, default: `false`) +- `a11y-label` - Accessibility label override (optional) +- `a11y-hint` - Accessibility hint (optional) + +## Events + +- `@press` - Livewire method to call when tapped + + + +## Examples + +### Variants + +@verbatim +```blade + + + + + + +``` +@endverbatim + +### Sizes + +@verbatim +```blade + + + + + +``` +@endverbatim + +### With icons + +@verbatim +```blade + +``` +@endverbatim + +### Loading state + +@verbatim +```blade + +``` +@endverbatim + +### Label as slot content + +@verbatim +```blade + + Save Changes + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Button; + +Button::make('Save') + ->variant('primary') + ->size('md') + ->icon('check') + ->iconTrailing('forward') + ->disabled(false) + ->loading(false) + ->onPress('save'); +``` + +- `make(string $label = '')` - Create a button with an optional label +- `variant(string $value)` - `primary | secondary | destructive | ghost` +- `size(string $value)` - `sm | md | lg` +- `icon(string $name)` - Leading icon +- `iconTrailing(string $name)` - Trailing icon +- `disabled(bool $value = true)` - Disable the button +- `loading(bool $value = true)` - Show a spinner and prevent presses +- `a11yLabel(string $value)` - Accessibility label override +- `a11yHint(string $value)` - Accessibility hint +- `onPress(string $method)` - Livewire method to invoke on tap diff --git a/resources/views/docs/mobile/3/edge-components/canvas.md b/resources/views/docs/mobile/3/edge-components/canvas.md new file mode 100644 index 00000000..334bfcbe --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/canvas.md @@ -0,0 +1,46 @@ +--- +title: Canvas +order: 605 +super_native: true +--- + + + +## Overview + +A drawing surface for [shape primitives](shapes). Behaves like a [``](column) for layout purposes — +children stack vertically by default. Use it as a semantic wrapper when grouping shapes. + +@verbatim +```blade + + + + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported. There are no canvas-specific props. + +## Children + +Accepts any EDGE elements as children. Typically used with [shape primitives](shapes) (``, +``, ``). + +For overlay-style layering of shapes use a [``](stack) instead — `` arranges children +along the column main axis, which is rarely what you want for free-form drawing. + +## Element + +```php +use Native\Mobile\Edge\Elements\Canvas; +use Native\Mobile\Edge\Elements\Rect; + +Canvas::make( + Rect::make()->width(100)->height(100)->bg('#3B82F6'), +); +``` + +- `make(Element ...$children)` - Create a canvas with children diff --git a/resources/views/docs/mobile/3/edge-components/card.md b/resources/views/docs/mobile/3/edge-components/card.md new file mode 100644 index 00000000..7da58114 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/card.md @@ -0,0 +1,106 @@ +--- +title: Card +order: 260 +super_native: true +--- + + + +## Overview + +A content surface with three semantic variants: + +- `filled` (default) — `theme.surfaceVariant` background, no stroke. Medium emphasis +- `outlined` — `theme.surface` + a `theme.outline` 1pt stroke. Low emphasis +- `elevated` — `theme.surface` + a soft drop shadow. High emphasis + +Per Model 3, all colors and the corner radius (`theme.radiusLg`) come from the theme. For custom visuals drop to a +styled `` or [``](pressable). + +@verbatim +```blade + + + Card Title + Card content goes here. + + +``` +@endverbatim + +## Props + +- `variant` - `filled` (default), `outlined`, or `elevated` +- `filled`, `outlined`, `elevated` - Boolean shortcuts for the corresponding variant +- `a11y-label` - Accessibility label (optional) +- `a11y-hint` - Accessibility hint (optional) + +## Events + +Cards honor the standard `@press` and `@longPress` directives — useful for tappable cards. + +## Children + +Accepts any EDGE elements as children. Typically wraps a `` so internal content has padding and gap +control. + +## Examples + +### Outlined card + +@verbatim +```blade + + + Settings + Manage your preferences + + +``` +@endverbatim + +### Tappable card + +@verbatim +```blade + + + {{ $item->title }} + {{ $item->excerpt }} + + +``` +@endverbatim + +### Card with image header + +@verbatim +```blade + + + + {{ $post->title }} + {{ $post->excerpt }} + + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Card; + +Card::make()->variant('elevated'); + +// Shortcuts: +Card::make()->filled(); +Card::make()->outlined(); +Card::make()->elevated(); +``` + +- `make()` - Create a card +- `variant(string $variant)` - `filled | outlined | elevated` +- `filled()`, `outlined()`, `elevated()` - Variant shortcuts +- `a11yLabel(string $value)` - Accessibility label +- `a11yHint(string $value)` - Accessibility hint diff --git a/resources/views/docs/mobile/3/edge-components/carousel.md b/resources/views/docs/mobile/3/edge-components/carousel.md new file mode 100644 index 00000000..df320d86 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/carousel.md @@ -0,0 +1,91 @@ +--- +title: Carousel +order: 270 +super_native: true +--- + + + +## Overview + +A horizontal paging carousel. Each child is sized to `item-width` and laid out in a horizontally-scrolling lazy +stack with `item-spacing` between items. + +@verbatim +```blade + + @foreach($posts as $post) + + {{ $post->title }} + {{ $post->excerpt }} + + @endforeach + +``` +@endverbatim + +## Props + +- `item-width` - Width of each child in dp (optional, float, default: `200`) +- `item-spacing` - Spacing between items in dp (optional, float, default: `8`) +- `variant` - Reserved for future variants (optional, string) + +## Children + +Accepts any EDGE elements as children. Each child is clipped to a 16dp rounded rectangle by the renderer, so +border-radius styling on the child itself is optional. + + + +## Examples + +### Featured cards + +@verbatim +```blade + + @foreach($features as $feature) + + {{ $feature->title }} + + {{ $feature->subtitle }} + + @endforeach + +``` +@endverbatim + +### Avatar strip + +@verbatim +```blade + + @foreach($contacts as $contact) + + + {{ $contact->name }} + + @endforeach + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Carousel; + +Carousel::make($child1, $child2, $child3) + ->itemWidth(280) + ->itemSpacing(12); +``` + +- `make(Element ...$children)` - Create a carousel with children +- `itemWidth(float $width)` - Width per item +- `itemSpacing(float $spacing)` - Spacing between items +- `variant(string $variant)` - Variant identifier (reserved) diff --git a/resources/views/docs/mobile/3/edge-components/checkbox.md b/resources/views/docs/mobile/3/edge-components/checkbox.md new file mode 100644 index 00000000..c74d5de4 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/checkbox.md @@ -0,0 +1,85 @@ +--- +title: Checkbox +order: 520 +super_native: true +--- + + + +## Overview + +A binary tick/untick control with an optional inline label. On iOS, renders as a tappable SF Symbol pair +(`checkmark.square.fill` / `square`) — SwiftUI has no native checkbox primitive. On Android, renders as a Material3 +`Checkbox`. + +Per Model 3, check/border/label colors come from the theme — no per-instance overrides. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +- `value` - Current checked state (optional, boolean, default: `false`) +- `label` - Inline label rendered to the right of the box (optional, string) +- `disabled` - Disable the checkbox (optional, boolean, default: `false`) +- `a11y-label` - Accessibility label (optional) +- `a11y-hint` - Accessibility hint (optional) + +## Events + +- `@change` - Livewire method called when toggled. Receives the new boolean value as a parameter + +## Two-way Binding + +Use `native:model` for automatic two-way binding with a Livewire boolean property. + +@verbatim +```blade + +``` +@endverbatim + +## Examples + +### Multiple options + +@verbatim +```blade + + + + + +``` +@endverbatim + +### Disabled + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Checkbox; + +Checkbox::make() + ->value($agreed) + ->label('I agree to the terms') + ->onChange('setAgreed'); +``` + +- `make()` - Create a checkbox +- `value(bool $checked)` - Current state +- `label(string $label)` - Inline label +- `disabled(bool $value = true)` - Disable the checkbox +- `a11yLabel(string $value)` - Accessibility label +- `a11yHint(string $value)` - Accessibility hint +- `syncMode(string $mode)`, `debounceMs(int $ms)` - Set by `native:model` modifiers +- `onChange(string $method)` - Livewire method invoked on toggle diff --git a/resources/views/docs/mobile/3/edge-components/chip.md b/resources/views/docs/mobile/3/edge-components/chip.md new file mode 100644 index 00000000..a87d3339 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/chip.md @@ -0,0 +1,85 @@ +--- +title: Chip +order: 525 +super_native: true +--- + + + +## Overview + +A compact selectable tag with a boolean active state and an optional leading icon. Renders as a capsule. + +When selected, the chip fills with `theme.primary` and uses `theme.onPrimary` for content. When unselected, it uses +`theme.surfaceVariant` with a `theme.outline` 1pt stroke. Per Model 3 — no per-instance color overrides. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +- `label` - Chip text (required, string). Can also be passed as the first argument to `make()` +- `selected` / `value` - Whether the chip is active (optional, boolean, default: `false`) +- `icon` - Leading [icon](icons) name (optional, string) +- `disabled` - Disable the chip (optional, boolean, default: `false`) +- `a11y-label` - Accessibility label (optional) +- `a11y-hint` - Accessibility hint (optional) + +## Events + +- `@change` - Livewire method called when toggled. Receives the new boolean value + +## Two-way Binding + +`native:model` binds the selected state to a Livewire boolean property: + +@verbatim +```blade + +``` +@endverbatim + +## Examples + +### Filter chip row + +@verbatim +```blade + + + + + +``` +@endverbatim + +### With icon + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Chip; + +Chip::make('Verified') + ->icon('check') + ->selected($onlyVerified) + ->onChange('toggleVerified'); +``` + +- `make(string $label = '')` - Create a chip with an optional label +- `label(string $label)` - Set the chip text +- `selected(bool $selected = true)` - Active state +- `icon(string $icon)` - Leading icon +- `disabled(bool $value = true)` - Disable the chip +- `a11yLabel(string $value)`, `a11yHint(string $value)` - Accessibility +- `syncMode(string $mode)` - Set by `native:model` modifiers +- `onChange(string $method)` - Livewire method invoked on toggle diff --git a/resources/views/docs/mobile/3/edge-components/column.md b/resources/views/docs/mobile/3/edge-components/column.md new file mode 100644 index 00000000..d5d7e1e5 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/column.md @@ -0,0 +1,109 @@ +--- +title: Column +order: 200 +super_native: true +--- + + + +## Overview + +A vertical flex container that stacks its children from top to bottom. This is the most commonly used layout element +and serves as the foundation for most screen layouts. + +@verbatim +```blade + + First item + Second item + Third item + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported. The most commonly used with columns: + +- `gap` - Vertical space between children in dp (optional, float) +- `align-items` - Horizontal alignment of children: `0`=start, `1`=center, `2`=end, `3`=stretch (optional, default: `0`) +- `justify-content` - Vertical distribution: `0`=start, `1`=center, `2`=end, `3`=space-between, `4`=space-around, `5`=space-evenly (optional, default: `0`) +- `safe-area` - Respect device safe area insets (optional, boolean) +- `padding` - Inner spacing, single value or array (optional) +- `bg` - Background color as hex (optional) + +## Children + +Accepts any EDGE elements as children. Children are arranged vertically from top to bottom. + +## Examples + +### Full-screen layout with safe area + +@verbatim +```blade + + My App + + + +``` +@endverbatim + +### Centered content + +@verbatim +```blade + + + Loading... + +``` +@endverbatim + +### Card-style layout + +@verbatim +```blade + + Card Title + Card description goes here. + + + + + +``` +@endverbatim + +### Space-between distribution + +@verbatim +```blade + + Top + Middle + Bottom + +``` +@endverbatim + +## Element + +```php +use Native\Mobile\Edge\Elements\Column; +use Native\Mobile\Edge\Elements\Text; + +Column::make( + Text::make('First'), + Text::make('Second'), +)->fill()->padding(16)->gap(12); +``` + +- `make(Element ...$children)` - Create a column with children. Layout / style fluent methods are inherited from + the base `Element` class — see [Layout & Styling](layout) diff --git a/resources/views/docs/mobile/3/edge-components/divider.md b/resources/views/docs/mobile/3/edge-components/divider.md new file mode 100644 index 00000000..b8aa9f81 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/divider.md @@ -0,0 +1,88 @@ +--- +title: Divider +order: 340 +super_native: true +--- + + + +## Overview + +A thin horizontal line separator. Renders as a 1pt rule. Color resolves from `border-color` if set, otherwise the +platform separator color. + +@verbatim +```blade + +``` +@endverbatim + +`` is an alias of `` exposed for use inside [side +navigation](side-nav). + +## Props + +All [shared layout and style attributes](layout) are supported. The most useful for dividers: + +- `border-color` - Line color as hex string (optional, default: platform separator color) +- `opacity` - Line opacity from 0.0 to 1.0 (optional) +- `margin` - Spacing around the divider (optional) + + + +## Examples + +### Basic separator + +@verbatim +```blade + + Section One + Some content here. + + Section Two + More content here. + +``` +@endverbatim + +### Colored divider with margin + +@verbatim +```blade + +``` +@endverbatim + +### In a list + +@verbatim +```blade + + @foreach($items as $item) + + {{ $item->name }} + + @unless($loop->last) + + @endunless + @endforeach + +``` +@endverbatim + +## Element + +```php +use Native\Mobile\Edge\Elements\Divider; + +Divider::make()->borderColor('#E2E8F0'); +``` + +- `make()` - Create a divider diff --git a/resources/views/docs/mobile/3/edge-components/icon.md b/resources/views/docs/mobile/3/edge-components/icon.md new file mode 100644 index 00000000..23557629 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/icon.md @@ -0,0 +1,93 @@ +--- +title: Icon +order: 330 +super_native: true +--- + + + +## Overview + +Displays a platform-native icon. On iOS, icons render as SF Symbols. On Android, icons render as Material Icons. +A smart mapping system translates common icon names across platforms automatically. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported, plus: + +- `name` - Icon name (required, string). See the [Icons](icons) reference for available names +- `size` - Icon size in dp (optional, float, default: `24`) +- `color` - Icon color as hex string (optional, default: platform default) + + + +## Examples + +### Basic icons + +@verbatim +```blade + + + + + + +``` +@endverbatim + +### Colored icon with label + +@verbatim +```blade + + + Verified + +``` +@endverbatim + +### Large icon + +@verbatim +```blade + + + No messages + +``` +@endverbatim + +### Platform-specific icon + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Icon; + +Icon::make('home')->size(24)->color('#1E293B'); +``` + +- `make(string $name = '')` - Create an icon +- `size(float $size)` - Icon size in dp +- `color(string $hex)` - Icon color diff --git a/resources/views/docs/mobile/3/edge-components/image.md b/resources/views/docs/mobile/3/edge-components/image.md new file mode 100644 index 00000000..2a3e4473 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/image.md @@ -0,0 +1,101 @@ +--- +title: Image +order: 320 +super_native: true +--- + + + +## Overview + +Displays an image from a URL. Loaded asynchronously by the native platform — `AsyncImage` on iOS, Coil on Android. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported, plus: + +- `src` - Image URL (required, string) +- `fit` - Content fit mode (optional, int, default: `1`): + - `0` / `1` — fit (scale to fit within bounds, preserving aspect ratio) + - `2` / `3` — fill (scale to fill bounds, cropping excess) +- `tint-color` - Apply a color tint as hex string (optional) + + + +## Examples + +### Basic image + +@verbatim +```blade + +``` +@endverbatim + +### Rounded avatar + +@verbatim +```blade + +``` +@endverbatim + +### Tinted icon image + +@verbatim +```blade + +``` +@endverbatim + +### Image in a card + +@verbatim +```blade + + + + Article Title + A brief description of the article. + + +``` +@endverbatim + +## Element + +```php +use Native\Mobile\Edge\Elements\Image; + +Image::make('https://example.com/photo.jpg') + ->fit(2) + ->tintColor('#7C3AED'); +``` + +- `make(string $src = '')` - Create an image with a source URL +- `fit(int $mode)` - `0`/`1` = fit, `2`/`3` = fill +- `tintColor(string $hex)` - Apply a color tint diff --git a/resources/views/docs/mobile/3/edge-components/introduction.md b/resources/views/docs/mobile/3/edge-components/introduction.md index a48d98ca..a3be6cf4 100644 --- a/resources/views/docs/mobile/3/edge-components/introduction.md +++ b/resources/views/docs/mobile/3/edge-components/introduction.md @@ -18,18 +18,66 @@ step that happens at runtime. You end up with pure, fast and flexible native com ## Available Components -Our first set of components are focused on navigation, framing your application with beautiful, platform-dependent UI -components. These familiar navigational elements will help your users feel immediately at home in your app and elevate -your app to feeling built for their chosen platform, just like a true native app. - -And all that without compromising your ability to build using tools and techniques you're already the most comfortable -with. - -For now, we have 3 main native components that you can configure: +EDGE provides a full suite of native UI components for building your app, from layout containers and typography to +interactive forms and navigation chrome. + +### Layout + +- **[Layout & Styling](layout)** - Shared sizing, spacing, flex, style, and event attributes available on all elements +- **[Screen](screen)** - Themed page-level container +- **[Column](column)** - Vertical flex container +- **[Row](row)** - Horizontal flex container +- **[Scroll View](scroll-view)** - Scrollable container with virtualization +- **[Stack](stack)** - Overlay container (ZStack) for layering elements +- **[Spacer](spacer)** - Flexible space element +- **[Pressable](pressable)** - Touch-sensitive container wrapper +- **[Card](card)** - Content surface with filled / outlined / elevated variants +- **[Web View](web-view)** - Embed web content as a native element and surround it with native UI + +### Content + +- **[Text](text)** - Text display with font sizing, weight, color, and alignment +- **[Image](image)** - Image display with fit modes and tinting +- **[Icon](icon)** - Platform-native icons (SF Symbols on iOS, Material Icons on Android) +- **[Divider](divider)** - Horizontal line separator +- **[Activity Indicator](activity-indicator)** - Loading spinner +- **[Progress Bar](progress-bar)** - Linear progress indicator +- **[Badge](badge)** - Count or label pill marker + +### Forms + +- **[Button](button)** - Tappable button with variants, sizes, and disabled / loading state +- **[Button Group](button-group)** - Segmented single-choice selector +- **[Text Input](text-input)** - Outlined and filled text input variants +- **[Toggle](toggle)** - On/off switch control +- **[Checkbox](checkbox)** - Tick/untick control with optional inline label +- **[Radio Group](radio-group)** - Single-choice radio selector +- **[Select](select)** - Dropdown picker +- **[Slider](slider)** - Continuous (or stepped) value selector +- **[Chip](chip)** - Compact selectable tag + +### Navigation - **[Bottom Navigation](bottom-nav)** - The always-accessible bottom navigation bar - **[Top Bar](top-bar)** - A title bar with action buttons - **[Side Navigation](side-nav)** - A slide-out navigation drawer +- **[Tab Row](tab-row)** - Horizontal tab strip for in-screen sectioning + +### Lists & data + +- **[List](list)** - Virtualized list with pull-to-refresh, end-reached, and swipe actions +- **[List Item](list)** - Material3 row with leading + trailing slot system +- **[Carousel](carousel)** - Horizontal paging carousel + +### Overlays + +- **[Bottom Sheet](bottom-sheet)** - Modal bottom sheet for contextual actions and forms +- **[Modal](modal)** - Full-screen modal overlay + +### Drawing + +- **[Canvas](canvas)** - Drawing surface for shape primitives +- **[Shapes](shapes)** - Rect, circle, and line elements ## How It Works diff --git a/resources/views/docs/mobile/3/edge-components/layout.md b/resources/views/docs/mobile/3/edge-components/layout.md new file mode 100644 index 00000000..6d05de27 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/layout.md @@ -0,0 +1,305 @@ +--- +title: Layout & Styling +order: 150 +super_native: true +--- + + + +## Overview + +Every EDGE element shares a common set of layout, styling, and event attributes. These are inherited from the base +`Element` class and can be applied to any native component -- containers, text, buttons, images, and more. + +This page documents the shared attribute system that powers the layout engine across all EDGE elements. + +## Sizing + +Control element dimensions with width, height, and fill attributes. + +@verbatim +```blade +{{-- Fixed dimensions (in dp) --}} + + ... + + +{{-- Fill available space --}} + + ... + + +{{-- Fill both axes --}} + + ... + + +{{-- Percentage width --}} + + ... + +``` +@endverbatim + +- `width` - Width in dp (float) or percentage string (e.g. `"50%"`) +- `height` - Height in dp (float) or percentage string +- `fill` - Fill both width and height of parent (boolean) +- `fill-width` - Fill parent width (boolean) +- `fill-height` - Fill parent height (boolean) +- `min-width` - Minimum width in dp (float) +- `max-width` - Maximum width in dp (float) +- `min-height` - Minimum height in dp (float) +- `max-height` - Maximum height in dp (float) +- `aspect-ratio` - Width-to-height ratio (float, e.g. `1.0` for square) + +## Spacing + +Padding and margin follow CSS shorthand conventions. Pass a single value for uniform spacing, or an array for +per-side control. + +@verbatim +```blade +{{-- Uniform padding --}} + + ... + + +{{-- Vertical | Horizontal --}} + + ... + + +{{-- Top | Right | Bottom | Left --}} + + ... + + +{{-- Uniform margin --}} + + ... + + +{{-- Gap between children --}} + + ... + +``` +@endverbatim + +- `padding` - Inner spacing. Single value (float) or array of 2-4 values +- `margin` - Outer spacing. Single value (float) or array of 2-4 values +- `gap` - Space between children in dp (float) + +## Flex Layout + +The layout engine uses a Flexbox-based system. Containers (column, row) arrange children along a main axis, and flex +properties control how children grow, shrink, and align. + +@verbatim +```blade +{{-- Grow to fill remaining space --}} + + ... + + +{{-- Prevent shrinking --}} + + ... + +``` +@endverbatim + +- `flex-grow` - How much this element grows relative to siblings (float, default: `0`) +- `flex-shrink` - How much this element shrinks when space is limited (float) +- `flex-basis` - Initial size before flex distribution (float or string) + + + +## Alignment + +Alignment values are integers that map to standard flex alignment: + +| Value | Meaning | +|-------|---------| +| `0` | start | +| `1` | center | +| `2` | end | +| `3` | stretch | +| `4` | baseline | + +@verbatim +```blade +{{-- Center children on both axes --}} + + ... + + +{{-- Cross-axis alignment (horizontal in a column) --}} + + Centered text + + +{{-- Main-axis distribution --}} + + Left + Right + +``` +@endverbatim + +- `align-items` - Cross-axis alignment for children (int, 0-4) +- `justify-content` - Main-axis distribution (int, 0=start, 1=center, 2=end, 3=space-between, 4=space-around, 5=space-evenly) +- `align-self` - Override parent's `align-items` for this element (int, 0-4) +- `center` - Shorthand: sets both `align-items` and `justify-content` to center (boolean) + + + +## Style + +Visual styling attributes that apply to any element. + +@verbatim +```blade + + ... + +``` +@endverbatim + +- `bg` - Background color as hex string (e.g. `"#FF0000"`, `"#80FF000080"` for alpha) +- `border-radius` - Corner rounding in dp (float) +- `border-width` - Border width in dp (float). Must be used together with `border-color` +- `border-color` - Border color as hex string. Must be used together with `border-width` +- `opacity` - Element opacity from 0.0 to 1.0 (float) +- `elevation` - Shadow depth (float). Maps to platform shadow/elevation + +## Events + +Any element can respond to press and long-press gestures. Use `@press` and `@longPress` directives to bind Livewire +methods. + +@verbatim +```blade + + Tap or long press me + +``` +@endverbatim + +- `@press` - Livewire method to call on tap +- `@longPress` - Livewire method to call on long press + +## Safe Area + +Respect the device's safe area insets (notch, home indicator, status bar) by adding the `safe-area` attribute. This is +typically applied to your outermost column. + +@verbatim +```blade + + {{-- Content will not overlap the notch or home indicator --}} + +``` +@endverbatim + +- `safe-area` - Inset content on both top and bottom edges (boolean) +- `safe-area-top` - Inset only the top edge (status bar / notch) +- `safe-area-bottom` - Inset only the bottom edge (home indicator) + +See [Safe Area](../the-basics/safe-area) for the full picture, including how the framework's [layout](../the-basics/layouts) +chrome already handles safe-area insets for you. + +## Visibility + +Hide elements without removing them from the tree. + +@verbatim +```blade + +``` +@endverbatim + +- `hidden` - Hide this element (boolean) + +## Dark Mode + +Override styles for dark mode using the `dark:` prefix with Tailwind classes, or pass a `dark` attribute array. + +@verbatim +```blade +{{-- Tailwind dark mode --}} + + + Adapts to dark mode + + +``` +@endverbatim + +Dark mode overrides currently support `bg`, `color`, `border-color`, `opacity`, and `font-size`. + +## Tailwind Classes + +EDGE includes a built-in Tailwind CSS parser that converts familiar utility classes into native layout attributes. Use +the `class` attribute on any element. + +@verbatim +```blade + + + Styled with Tailwind + + +``` +@endverbatim + +### Supported Tailwind classes + +| Category | Classes | +|----------|---------| +| Width | `w-full`, `w-{n}`, `w-1/2`, `w-1/3`, `w-[100]` | +| Height | `h-full`, `h-{n}`, `h-[100]` | +| Padding | `p-{n}`, `px-{n}`, `py-{n}`, `pt-{n}`, `pr-{n}`, `pb-{n}`, `pl-{n}` | +| Margin | `m-{n}`, `mx-{n}`, `my-{n}`, `mt-{n}`, `mr-{n}`, `mb-{n}`, `ml-{n}` | +| Gap | `gap-{n}` | +| Background | `bg-{color}-{shade}`, `bg-white`, `bg-black`, `bg-[#hex]` | +| Text color | `text-{color}-{shade}`, `text-white`, `text-black`, `text-[#hex]` | +| Text size | `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl` ... `text-6xl` | +| Font weight | `font-thin`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold` | +| Border | `border`, `border-{n}`, `border-{color}-{shade}`, `border-[#hex]` | +| Rounded | `rounded`, `rounded-sm` ... `rounded-full`, `rounded-[16]` | +| Shadow | `shadow`, `shadow-sm` ... `shadow-2xl`, `shadow-none` | +| Opacity | `opacity-{0-100}` | +| Alignment | `items-start`, `items-center`, `items-end`, `items-stretch` | +| Justify | `justify-start`, `justify-center`, `justify-end`, `justify-between`, `justify-around`, `justify-evenly` | +| Self | `self-start`, `self-center`, `self-end`, `self-stretch` | +| Flex | `flex-1`, `flex-grow`, `flex-grow-0`, `flex-shrink`, `flex-shrink-0` | +| Safe area | `safe-area`, `safe-area-top`, `safe-area-bottom` | +| Position | `absolute`, `relative`, `top-[N]`, `right-[N]`, `bottom-[N]`, `left-[N]` | +| Text align | `text-left`, `text-center`, `text-right` | + + diff --git a/resources/views/docs/mobile/3/edge-components/list.md b/resources/views/docs/mobile/3/edge-components/list.md new file mode 100644 index 00000000..561e0fc7 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/list.md @@ -0,0 +1,205 @@ +--- +title: List +order: 280 +super_native: true +--- + + + +## Overview + +A virtualized list container. On iOS, renders as a SwiftUI `List` with native pull-to-refresh and trailing +swipe-to-delete. On Android, renders as a `LazyColumn` / `LazyRow`. + +Pair with [``](#list-item) for Material3 list rows, or use any EDGE element as a child. + +@verbatim +```blade + + @foreach($contacts as $contact) + + @endforeach + +``` +@endverbatim + +## Props + +- `horizontal` - Lay out children horizontally instead of vertically (optional, boolean, default: `false`) +- `shows-indicators` - Show scroll indicators (optional, boolean, default: `false`) [iOS] +- `separator` - Render dividers between rows (optional, boolean, default: `false`) [iOS] +- `on-refresh` - Livewire method called on pull-to-refresh (optional, string) [iOS] +- `on-end-reached` - Livewire method called when the user nears the end of the list (optional, string) + +## Children + +Accepts any EDGE elements as children. `` is the canonical child for Material3-style rows. + +## List Item + +A pre-styled Material3 row with a headline, optional supporting + overline text, and configurable leading + trailing +content slots. + +@verbatim +```blade + +``` +@endverbatim + +### Text props + +- `headline` - Primary text (required, string) +- `supporting` - Secondary text rendered below the headline (optional, string) +- `overline` - Small caption rendered above the headline (optional, string) + +### Leading slot (mutually exclusive) + +- `leadingIcon` - Icon name rendered as a leading icon +- `leadingAvatar` - URL of a circular avatar image +- `leadingMonogram` - 1-2 character monogram (combine with `leadingMonogramColor`) +- `leadingMonogramColor` - Hex color for monogram background +- `leadingImage` - URL of a square image with a small radius +- `leadingCheckbox` - Boolean value for a leading checkbox +- `leadingRadio` - Boolean value for a leading radio button + +### Trailing slot (mutually exclusive) + +- `trailingIcon` - Icon name rendered as a trailing icon +- `trailingText` - Trailing text label +- `trailingCheckbox` - Boolean value for a trailing checkbox +- `trailingSwitch` - Boolean value for a trailing switch [Android] +- `trailingIconButton` - Icon name for a tappable trailing button + +### Color overrides + +- `headlineColor`, `supportingColor`, `overlineColor` - Hex colors for the text styles +- `containerColor` - Row background color +- `leadingIconColor`, `trailingIconColor`, `trailingTextColor` - Colors for the slot content + +### State + +- `disabled` - Disable the row (optional, boolean, default: `false`) +- `tonalElevation` - Tonal elevation in dp [Android] +- `shadowElevation` - Shadow elevation in dp [Android] + +### Events + +- `@press` / `@longPress` - Standard press handlers on the row +- `on-swipe-delete` - Livewire method invoked when the user swipes the row to delete [iOS] + +## Examples + +### Settings menu + +@verbatim +```blade + + + + + + +``` +@endverbatim + +### Swipe-to-delete with pull-to-refresh + +@verbatim +```blade + + @foreach($tasks as $task) + + @endforeach + +``` +@endverbatim + +### Infinite scroll + +@verbatim +```blade + + @foreach($posts as $post) + + @endforeach + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\NativeList; +use Nativephp\NativeUi\Elements\ListItem; + +NativeList::make( + ListItem::make('Profile')->leadingIcon('person')->trailingIcon('forward'), + ListItem::make('Settings')->leadingIcon('settings')->trailingIcon('forward'), +) + ->separator() + ->onRefresh('refresh') + ->onEndReached('loadMore'); +``` + +### `NativeList` methods + +- `make(Element ...$children)` - Create a list with children +- `horizontal(bool $value = true)` - Horizontal layout +- `showsIndicators(bool $value = true)` - Show scroll indicators +- `separator(bool $value = true)` - Render dividers between rows +- `onRefresh(string $method)` - Pull-to-refresh handler +- `onEndReached(string $method)` - End-reached handler + +### `ListItem` methods + +Text: + +- `make(string $headline = '')`, `supporting(string $text)`, `overline(string $text)` + +Leading slot: + +- `leadingIcon(string $icon)` +- `leadingAvatar(string $url)` +- `leadingMonogram(string $initials, ?string $color = null)` +- `leadingImage(string $url)` +- `leadingCheckbox(bool $checked = false)` +- `leadingRadio(bool $selected = false)` + +Trailing slot: + +- `trailingIcon(string $icon)` +- `trailingText(string $text)` +- `trailingCheckbox(bool $checked = false)` +- `trailingSwitch(bool $checked = false)` +- `trailingIconButton(string $icon)` + +Styling: + +- `headlineColor`, `supportingColor`, `overlineColor`, `containerColor`, + `leadingIconColor`, `trailingIconColor`, `trailingTextColor` (all `(string $color)`) +- `tonalElevation(float $dp)`, `shadowElevation(float $dp)` + +Callbacks: + +- `onLeadingChange(string $method)`, `onTrailingChange(string $method)`, + `onTrailingPress(string $method)`, `onSwipeDelete(string $method)` +- `disabled(bool $disabled = true)` diff --git a/resources/views/docs/mobile/3/edge-components/modal.md b/resources/views/docs/mobile/3/edge-components/modal.md new file mode 100644 index 00000000..dbe3e4d8 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/modal.md @@ -0,0 +1,93 @@ +--- +title: Modal +order: 710 +super_native: true +--- + + + +## Overview + +A full-screen modal overlay. Visibility is driven by the `visible` prop. Use a [bottom sheet](bottom-sheet) for +contextual actions; reach for `` when you want the entire screen covered (e.g. an onboarding flow, +image preview, or detail view). + +Per Model 3, backdrop and surface colors come from `theme.background`. The close icon uses `theme.onSurfaceVariant`. + +@verbatim +```blade + + + Details + {{ $item->description }} + + +``` +@endverbatim + +## Props + +- `visible` - Whether the modal is shown (required, boolean) +- `dismissible` - Render a close icon and allow swipe-to-dismiss (optional, boolean, default: `true`) +- `a11y-label` - Accessibility label (optional) + +## Events + +- `@dismiss` - Livewire method called when the user dismisses the modal (close button tap or swipe). Always handle + this to keep your `visible` state in sync + +## Children + +Accepts any EDGE elements as children. The children are rendered inside the modal's content area below the +auto-supplied close button (when `dismissible`). + + + +## Examples + +### Image preview + +@verbatim +```blade + + + + + +``` +@endverbatim + +### Non-dismissible loading modal + +@verbatim +```blade + + + + Processing... + + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Modal; + +Modal::make() + ->visible($showDetails) + ->dismissible(true) + ->onDismiss('closeDetails'); +``` + +- `make()` - Create a modal +- `visible(bool $value = true)` - Toggle visibility +- `dismissible(bool $value = true)` - Allow user dismissal +- `a11yLabel(string $value)` - Accessibility label +- `onDismiss(string $method)` - Livewire method invoked on dismissal diff --git a/resources/views/docs/mobile/3/edge-components/pressable.md b/resources/views/docs/mobile/3/edge-components/pressable.md new file mode 100644 index 00000000..0104ceb4 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/pressable.md @@ -0,0 +1,103 @@ +--- +title: Pressable +order: 250 +super_native: true +--- + + + +## Overview + +A touch-sensitive container that wraps its children in a tappable area. Pressable is structurally identical to a column +but is specifically designed for handling tap and long-press gestures on a group of elements. + +While any element can handle `@press` and `@longPress` events, `` makes the intent explicit and +provides a clear tap target that wraps multiple children. + +@verbatim +```blade + + {{ $item->name }} + {{ $item->description }} + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported. There are no pressable-specific props beyond the +standard event handlers. + +## Events + +- `@press` - Livewire method to call on tap +- `@longPress` - Livewire method to call on long press + +## Children + +Accepts any EDGE elements as children. Children are arranged vertically (like a column). + +## Examples + +### Tappable list item + +@verbatim +```blade +@foreach($items as $item) + + + + + {{ $item->name }} + {{ $item->subtitle }} + + + + + @unless($loop->last) + + @endunless +@endforeach +``` +@endverbatim + +### Card with tap and long press + +@verbatim +```blade + + {{ $post->title }} + {{ $post->excerpt }} + +``` +@endverbatim + +### Navigation with @navigate + +@verbatim +```blade + + {{ $item->name }} + +``` +@endverbatim + +## Element + +```php +use Native\Mobile\Edge\Elements\Pressable; + +Pressable::make($child1, $child2)->onPress('handleTap'); +``` + +- `make(Element ...$children)` - Create a pressable with children. Inherits the standard layout / style API from + the base `Element` class diff --git a/resources/views/docs/mobile/3/edge-components/progress-bar.md b/resources/views/docs/mobile/3/edge-components/progress-bar.md new file mode 100644 index 00000000..3514c966 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/progress-bar.md @@ -0,0 +1,86 @@ +--- +title: Progress Bar +order: 355 +super_native: true +--- + + + +## Overview + +A linear progress indicator. When `value` is supplied, renders as determinate progress in `[0.0, 1.0]`. Without a +value (or with `indeterminate`), renders an animated wave. + +For a circular spinner use [``](activity-indicator) instead. + +Per Model 3, the progress fill uses `theme.primary` and the track uses `theme.surfaceVariant`. The optional `color` +prop is an escape hatch for non-theme containers. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +- `value` - Current progress in `[0.0, 1.0]` (optional, float). Setting `value` implies `indeterminate=false` +- `indeterminate` - Force indeterminate mode (optional, boolean, default: `false` when `value` is set, otherwise `true`) +- `color` - Override the fill color as hex string (optional) +- `track-color` - Override the track color as hex string (optional) +- `a11y-label` - Accessibility label (optional) + + + +## Examples + +### Determinate + +@verbatim +```blade + + + Uploading + {{ round($progress * 100) }}% + + + +``` +@endverbatim + +### Indeterminate + +@verbatim +```blade + +``` +@endverbatim + +### With color override + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\ProgressBar; + +ProgressBar::make()->value(0.65); + +ProgressBar::make()->indeterminate(); +``` + +- `make()` - Create a progress bar +- `value(float $val)` - Determinate progress in `[0.0, 1.0]` +- `indeterminate(bool $value = true)` - Force indeterminate mode +- `color(string $hex)` - Override the fill tint +- `trackColor(string $hex)` - Override the track color +- `a11yLabel(string $value)` - Accessibility label diff --git a/resources/views/docs/mobile/3/edge-components/radio-group.md b/resources/views/docs/mobile/3/edge-components/radio-group.md new file mode 100644 index 00000000..e433e0b8 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/radio-group.md @@ -0,0 +1,116 @@ +--- +title: Radio Group +order: 530 +super_native: true +--- + + + +## Overview + +A single-choice container holding `` children. The group owns the selection; each child declares its +own `value` and label. + +Per Model 3, all colors come from theme tokens. + +@verbatim +```blade + + + + + +``` +@endverbatim + +## Props (Group) + +- `value` - Currently selected `value` string (optional). Use `native:model` for two-way binding +- `label` - Label text rendered above the group (optional, string) +- `disabled` - Disable the entire group (optional, boolean, default: `false`) +- `a11y-label` - Accessibility label (optional) +- `a11y-hint` - Accessibility hint (optional) + +## Events + +- `@change` - Livewire method called when the selection changes. Receives the new value as a parameter + +## Two-way Binding + +`native:model` binds the group's selected value to a Livewire string property: + +@verbatim +```blade + + + + +``` +@endverbatim + +## Children + +`` declares a single option: + +- `value` - The option's value (required, string). Must be unique within the group +- `label` - Inline label (optional, string) +- `disabled` - Disable just this option (optional, boolean, default: `false`) + +## Examples + +### Plan picker + +@verbatim +```blade + + + + + + +``` +@endverbatim + +### Manual handler + +@verbatim +```blade + + + + + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\RadioGroup; +use Nativephp\NativeUi\Elements\Radio; + +RadioGroup::make( + Radio::make('free')->label('Free'), + Radio::make('pro')->label('Pro'), + Radio::make('team')->label('Team'), +) + ->value($plan) + ->label('Choose a plan') + ->onChange('setPlan'); +``` + +### `RadioGroup` methods + +- `make(Element ...$children)` - Create a group with radio children +- `value(string $selectedValue)` - Currently selected value +- `label(string $text)` - Group label +- `disabled(bool $value = true)` - Disable the group +- `a11yLabel(string $value)`, `a11yHint(string $value)` - Accessibility +- `syncMode(string $mode)` - Set by `native:model` modifiers +- `onChange(string $method)` - Livewire method invoked on selection change + +### `Radio` methods + +- `make(string $value = '')` - Create a radio with a value +- `label(string $label)` - Inline label +- `disabled(bool $value = true)` - Disable the option diff --git a/resources/views/docs/mobile/3/edge-components/row.md b/resources/views/docs/mobile/3/edge-components/row.md new file mode 100644 index 00000000..817664d2 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/row.md @@ -0,0 +1,90 @@ +--- +title: Row +order: 210 +super_native: true +--- + + + +## Overview + +A horizontal flex container that arranges its children from left to right. Use rows for side-by-side layouts, toolbars, +and inline groupings. + +@verbatim +```blade + + + 4.8 Rating + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported. The most commonly used with rows: + +- `gap` - Horizontal space between children in dp (optional, float) +- `align-items` - Vertical alignment of children: `0`=start, `1`=center, `2`=end, `3`=stretch (optional, default: `0`) +- `justify-content` - Horizontal distribution: `0`=start, `1`=center, `2`=end, `3`=space-between, `4`=space-around, `5`=space-evenly (optional, default: `0`) +- `padding` - Inner spacing, single value or array (optional) +- `bg` - Background color as hex (optional) + +## Children + +Accepts any EDGE elements as children. Children are arranged horizontally from left to right. + +## Examples + +### Toolbar with spacer + +@verbatim +```blade + + Title + + + +``` +@endverbatim + +### Evenly spaced items + +@verbatim +```blade + + One + Two + Three + +``` +@endverbatim + +### Inline label and value + +@verbatim +```blade + + Status + + + Active + + +``` +@endverbatim + +## Element + +```php +use Native\Mobile\Edge\Elements\Row; +use Native\Mobile\Edge\Elements\Text; + +Row::make( + Text::make('Left'), + Text::make('Right'), +)->gap(8)->alignItems(1); +``` + +- `make(Element ...$children)` - Create a row with children. Layout / style fluent methods are inherited from the + base `Element` class — see [Layout & Styling](layout) diff --git a/resources/views/docs/mobile/3/edge-components/screen.md b/resources/views/docs/mobile/3/edge-components/screen.md new file mode 100644 index 00000000..24259100 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/screen.md @@ -0,0 +1,56 @@ +--- +title: Screen +order: 100 +super_native: true +--- + + + +## Overview + +A themed page-level container. Applies `theme.background` as the full-bleed backdrop and `theme.onBackground` as +the default content color for descendants. Adapts automatically to the system's light/dark mode. + +Use it as the root of a page so background and default content color follow your theme everywhere — no need to +add `bg-...` classes to every screen. + +@verbatim +```blade + + + + Welcome + Your dashboard. + + + +``` +@endverbatim + +## Props + +`` is intentionally props-less — it's a contextual backdrop, not a styled element. Layout +attributes (`width`, `margin`, etc.) are still accepted in case you need to adjust position inside a parent, but +typical usage is bare. + +## Children + +Accepts any EDGE elements as children. Most commonly wraps a single [``](scroll-view) or +[``](column). + + + +## Element + +```php +use Nativephp\NativeUi\Elements\Screen; + +Screen::make(); +``` + +- `make()` - Create a screen container diff --git a/resources/views/docs/mobile/3/edge-components/scroll-view.md b/resources/views/docs/mobile/3/edge-components/scroll-view.md new file mode 100644 index 00000000..9b2e0924 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/scroll-view.md @@ -0,0 +1,108 @@ +--- +title: Scroll View +order: 220 +super_native: true +--- + + + +## Overview + +A scrollable container for content that exceeds the available screen space. By default it scrolls vertically, but can +be configured for horizontal scrolling. On the native side, this uses `LazyColumn`/`LazyRow` on Android and +`ScrollView` on iOS for efficient rendering. + +@verbatim +```blade + + + @foreach($items as $item) + {{ $item->name }} + @endforeach + + +``` +@endverbatim + +## Props + +All [shared layout and style attributes](layout) are supported, plus: + +- `horizontal` - Scroll horizontally instead of vertically (optional, boolean, default: `false`) +- `shows-indicators` - Show scroll indicators (optional, boolean, default: `true`) [iOS] + + + +## Children + +Accepts any EDGE elements as children. Typically wraps a single `` or `` that contains the +scrollable content. + +## Examples + +### Vertical list + +@verbatim +```blade + + + @foreach($posts as $post) + + {{ $post->title }} + {{ $post->excerpt }} + + @endforeach + + +``` +@endverbatim + +### Horizontal carousel + +@verbatim +```blade + + + @foreach($categories as $category) + + {{ $category->name }} + + @endforeach + + +``` +@endverbatim + +### Full-page scrollable layout + +@verbatim +```blade + + + Welcome + + Scroll down to see more content. + + {{-- Long content here --}} + + +``` +@endverbatim + + diff --git a/resources/views/docs/mobile/3/edge-components/select.md b/resources/views/docs/mobile/3/edge-components/select.md new file mode 100644 index 00000000..953dc5a5 --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/select.md @@ -0,0 +1,99 @@ +--- +title: Select +order: 540 +super_native: true +--- + + + +## Overview + +A single-choice dropdown picker over a flat list of strings. On iOS, renders as a SwiftUI `Menu` (popover); on +Android, as an M3 `ExposedDropdownMenuBox` with an outlined trigger. + +Per Model 3, colors and borders come from theme tokens. + +@verbatim +```blade + +``` +@endverbatim + +## Props + +- `options` - Array of option strings (required, array) +- `value` - Currently selected option string (optional). Use `native:model` for two-way binding +- `label` - Label rendered above the trigger (optional, string) +- `placeholder` - Text shown when nothing is selected (optional, string) +- `disabled` - Disable the picker (optional, boolean, default: `false`) +- `a11y-label` - Accessibility label (optional) +- `a11y-hint` - Accessibility hint (optional) + +## Events + +- `@change` - Livewire method called when the selection changes. Receives the new option string + +## Two-way Binding + +`native:model` binds the selected option to a Livewire string property: + +@verbatim +```blade + +``` +@endverbatim + +## Examples + +### Country picker + +@verbatim +```blade + +``` +@endverbatim + +### Manual handler + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Nativephp\NativeUi\Elements\Select; + +Select::make() + ->label('Country') + ->placeholder('Select country') + ->options(['Australia', 'Canada', 'United States']) + ->value($country) + ->onChange('setCountry'); +``` + +- `make()` - Create a select +- `options(array $options)` - Option strings +- `value(string $val)` - Current selection +- `label(string $text)` - Label text +- `placeholder(string $text)` - Empty-state text +- `disabled(bool $value = true)` - Disable the picker +- `a11yLabel(string $value)`, `a11yHint(string $value)` - Accessibility +- `syncMode(string $mode)` - Set by `native:model` modifiers +- `onChange(string $method)` - Livewire method invoked on change diff --git a/resources/views/docs/mobile/3/edge-components/shapes.md b/resources/views/docs/mobile/3/edge-components/shapes.md new file mode 100644 index 00000000..b768d34a --- /dev/null +++ b/resources/views/docs/mobile/3/edge-components/shapes.md @@ -0,0 +1,120 @@ +--- +title: Shapes +order: 600 +super_native: true +--- + + + +## Overview + +Shape primitives for drawing simple geometric forms. Three primitives are available: + +- `` — rectangle +- `` — circle +- `` — horizontal rule + +These are typically placed inside a [``](canvas) or used standalone for decorative accents. + +## Rect + +A rectangle filled with `bg`. All [shared layout and style attributes](layout) apply, so border, radius, opacity, +and elevation behave as on any other element. + +@verbatim +```blade + +``` +@endverbatim + +### Props + +- `left` - X position offset in dp (optional, float). Used inside an absolutely-positioned parent +- `top` - Y position offset in dp (optional, float) + +`` may optionally wrap children if you need to layer content on top of the fill. + +## Circle + +A circle filled with `bg`. Defaults to `border-radius: 9999` so any square-ish frame appears as a circle. For a +perfect circle use equal `width` and `height`. + +@verbatim +```blade + +``` +@endverbatim + +### Props + +- `left` - X position offset in dp (optional, float) +- `top` - Y position offset in dp (optional, float) + +`` is a self-closing element. It does not accept children. + +## Line + +A 1pt horizontal rule across the available width. + +@verbatim +```blade + +``` +@endverbatim + +### Props + +All [shared layout and style attributes](layout) are supported. The most useful: + +- `border-color` - Line color as hex string (optional, default: platform separator color) +- `border-width` - Stroke thickness in dp (optional, float, default: `1`) + + + +## Examples + +### Status dot + +@verbatim +```blade + +``` +@endverbatim + +### Colored badge background + +@verbatim +```blade + + New + +``` +@endverbatim + +### Decorative separator + +@verbatim +```blade + +``` +@endverbatim + +## Element + +```php +use Native\Mobile\Edge\Elements\Rect; +use Native\Mobile\Edge\Elements\Circle; +use Native\Mobile\Edge\Elements\Line; + +Rect::make(); +Circle::make(); +Line::make(); +``` + +All three expose `make()` and inherit the standard layout / style fluent API. diff --git a/resources/views/docs/mobile/3/edge-components/side-nav.md b/resources/views/docs/mobile/3/edge-components/side-nav.md index fd3dde74..778cc8ec 100644 --- a/resources/views/docs/mobile/3/edge-components/side-nav.md +++ b/resources/views/docs/mobile/3/edge-components/side-nav.md @@ -63,7 +63,8 @@ A slide-out navigation drawer with support for groups, headers, and dividers. ## Props - `gestures-enabled` - Swipe to open (default: `false`) [Android] -- `dark` - Force dark mode (optional) +- `label-visibility` - `labeled` (default), `selected`, or `unlabeled` (optional) +- `dark` - Force dark mode (optional, boolean)