@ticatec/uniface-element 0.2.4 → 0.3.1

package/dist/breadcrumbs/README.md

@@ -0,0 +1,442 @@
+# Breadcrumbs Component
+
+A navigation component that shows the user's current location in a hierarchical structure, helping users understand where they are and navigate back to previous levels.
+
+## Features
+
+- **Hierarchical Navigation**: Display path from root to current location
+- **Clickable Items**: Navigate to any previous level (except current)
+- **Custom Separators**: Configurable separator between breadcrumb items
+- **Custom Data**: Associate any data with breadcrumb items
+- **Click Handlers**: Custom logic for navigation actions
+- **Responsive**: Adapts to container width
+
+## Basic Usage
+
+```svelte
+<script>
+import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+
+const breadcrumbItems: Breadcrumb[] = [
+  { label: 'Home', data: { path: '/' } },
+  { label: 'Products', data: { path: '/products' } },
+  { label: 'Electronics', data: { path: '/products/electronics' } },
+  { label: 'Smartphones', data: { path: '/products/electronics/smartphones' } }
+];
+
+const handleItemClick = (data: any) => (event: MouseEvent) => {
+  console.log('Navigate to:', data.path);
+  // Handle navigation logic
+};
+</script>
+
+<Breadcrumbs 
+  items={breadcrumbItems} 
+  onItemClick={handleItemClick} 
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Breadcrumb[]` | `[]` | Array of breadcrumb items |
+| `separator` | `string` | `"/"` | Separator character between items |
+| `onItemClick` | `(item: any) => (event: MouseEvent) => void` | - | Click handler for breadcrumb items |
+| `style` | `string` | `''` | Custom CSS styles |
+
+## Breadcrumb Interface
+
+```typescript
+interface Breadcrumb {
+  label: string;    // Display text for the breadcrumb
+  data: any;        // Associated data (e.g., route, ID, etc.)
+}
+```
+
+## Examples
+
+### Basic File System Navigation
+
+```svelte
+<script>
+const fileSystemPath = [
+  { label: 'Documents', data: { path: '/documents' } },
+  { label: 'Projects', data: { path: '/documents/projects' } },
+  { label: 'MyApp', data: { path: '/documents/projects/myapp' } },
+  { label: 'src', data: { path: '/documents/projects/myapp/src' } }
+];
+
+const navigateToFolder = (data: any) => (event: MouseEvent) => {
+  window.location.href = data.path;
+};
+</script>
+
+<Breadcrumbs 
+  items={fileSystemPath}
+  onItemClick={navigateToFolder}
+  separator=" > "
+/>
+```
+
+### E-commerce Category Navigation
+
+```svelte
+<script>
+const categoryPath = [
+  { label: 'All Categories', data: { categoryId: null } },
+  { label: 'Electronics', data: { categoryId: 'electronics' } },
+  { label: 'Computers', data: { categoryId: 'computers' } },
+  { label: 'Laptops', data: { categoryId: 'laptops' } }
+];
+
+const goToCategory = (data: any) => (event: MouseEvent) => {
+  if (data.categoryId) {
+    router.push(`/category/${data.categoryId}`);
+  } else {
+    router.push('/categories');
+  }
+};
+</script>
+
+<Breadcrumbs 
+  items={categoryPath}
+  onItemClick={goToCategory}
+  separator=" › "
+/>
+```
+
+### Admin Panel Navigation
+
+```svelte
+<script>
+const adminPath = [
+  { label: 'Dashboard', data: { route: '/admin' } },
+  { label: 'User Management', data: { route: '/admin/users' } },
+  { label: 'Edit User', data: { route: '/admin/users/edit', userId: 123 } }
+];
+
+const navigateToAdminPage = (data: any) => (event: MouseEvent) => {
+  // Custom navigation logic
+  adminRouter.navigate(data.route);
+};
+</script>
+
+<Breadcrumbs 
+  items={adminPath}
+  onItemClick={navigateToAdminPage}
+/>
+```
+
+### Documentation Site
+
+```svelte
+<script>
+const docsPath = [
+  { label: 'Documentation', data: { section: 'home' } },
+  { label: 'Components', data: { section: 'components' } },
+  { label: 'Form Controls', data: { section: 'forms' } },
+  { label: 'TextEditor', data: { section: 'texteditor' } }
+];
+
+const goToDocsSection = (data: any) => (event: MouseEvent) => {
+  scrollToSection(data.section);
+};
+</script>
+
+<Breadcrumbs 
+  items={docsPath}
+  onItemClick={goToDocsSection}
+  separator=" • "
+/>
+```
+
+### Custom Separator with Icons
+
+```svelte
+<script>
+const projectPath = [
+  { label: 'Workspace', data: { id: 'workspace' } },
+  { label: 'Project Alpha', data: { id: 'project-alpha' } },
+  { label: 'Settings', data: { id: 'settings' } }
+];
+</script>
+
+<Breadcrumbs 
+  items={projectPath}
+  onItemClick={handleNavigation}
+  separator=" 🔹 "
+  style="font-size: 14px; color: #666;"
+/>
+```
+
+### With Custom Styling
+
+```svelte
+<Breadcrumbs 
+  items={breadcrumbs}
+  onItemClick={navigate}
+  separator=" / "
+  style="
+    background: #f8f9fa; 
+    padding: 8px 16px; 
+    border-radius: 4px; 
+    font-size: 13px;
+  "
+/>
+```
+
+### Dynamic Breadcrumbs
+
+```svelte
+<script>
+let currentPath = [];
+
+// Build breadcrumbs based on current route
+$: breadcrumbs = buildBreadcrumbs($page.url.pathname);
+
+function buildBreadcrumbs(pathname) {
+  const segments = pathname.split('/').filter(Boolean);
+  const items = [{ label: 'Home', data: { path: '/' } }];
+  
+  let currentPath = '';
+  segments.forEach(segment => {
+    currentPath += `/${segment}`;
+    items.push({
+      label: formatSegment(segment),
+      data: { path: currentPath }
+    });
+  });
+  
+  return items;
+}
+
+function formatSegment(segment) {
+  return segment.charAt(0).toUpperCase() + segment.slice(1);
+}
+
+const navigateTo = (data) => (event) => {
+  goto(data.path);
+};
+</script>
+
+<Breadcrumbs 
+  items={breadcrumbs}
+  onItemClick={navigateTo}
+/>
+```
+
+## Behavior
+
+### Click Interaction
+- All breadcrumb items except the last one are clickable
+- The last item (current location) is not clickable and appears as plain text
+- Click handlers receive the associated data object from the breadcrumb item
+
+### Navigation Pattern
+- Typically used for hierarchical navigation
+- Helps users understand their current location
+- Provides quick access to parent levels
+
+## Styling
+
+The component uses the following CSS classes:
+
+- `.uniface-breadcrumbs` - Main container
+- `.breadcrumb` - Individual breadcrumb item
+
+### Example CSS
+
+```css
+.uniface-breadcrumbs {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 4px;
+  font-size: 14px;
+  color: #666;
+}
+
+.breadcrumb {
+  cursor: pointer;
+  color: #007acc;
+  text-decoration: none;
+}
+
+.breadcrumb:hover {
+  text-decoration: underline;
+}
+
+.breadcrumb:last-child {
+  cursor: default;
+  color: #333;
+  font-weight: 500;
+}
+
+/* Responsive design */
+@media (max-width: 768px) {
+  .uniface-breadcrumbs {
+    font-size: 12px;
+  }
+}
+```
+
+## Common Patterns
+
+### Page Title Integration
+
+```svelte
+<div class="page-header">
+  <Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
+  <h1>{currentPageTitle}</h1>
+</div>
+```
+
+### With Loading State
+
+```svelte
+<script>
+let loading = false;
+let breadcrumbs = [];
+
+const loadBreadcrumbs = async (pageId) => {
+  loading = true;
+  try {
+    breadcrumbs = await fetchBreadcrumbs(pageId);
+  } finally {
+    loading = false;
+  }
+};
+</script>
+
+{#if loading}
+  <div class="breadcrumb-skeleton">Loading...</div>
+{:else}
+  <Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
+{/if}
+```
+
+### Truncated Long Paths
+
+```svelte
+<script>
+const MAX_ITEMS = 4;
+
+$: displayItems = breadcrumbs.length > MAX_ITEMS
+  ? [
+      breadcrumbs[0],
+      { label: '...', data: { truncated: true } },
+      ...breadcrumbs.slice(-2)
+    ]
+  : breadcrumbs;
+
+const handleClick = (data) => (event) => {
+  if (data.truncated) {
+    // Show dropdown with hidden items
+    showFullPath = true;
+    return;
+  }
+  navigate(data);
+};
+</script>
+
+<Breadcrumbs 
+  items={displayItems}
+  onItemClick={handleClick}
+/>
+```
+
+## Accessibility
+
+- Use semantic navigation structure
+- Provide clear visual distinction between clickable and non-clickable items
+- Ensure adequate color contrast
+- Consider ARIA labels for screen readers
+
+```svelte
+<nav aria-label="Breadcrumb navigation">
+  <Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
+</nav>
+```
+
+## Integration with Routing
+
+### SvelteKit Integration
+
+```svelte
+<script>
+import { page } from '$app/stores';
+import { goto } from '$app/navigation';
+
+$: breadcrumbs = generateBreadcrumbs($page.route.id);
+
+function generateBreadcrumbs(routeId) {
+  // Generate breadcrumbs based on route structure
+  return routeSegments.map(segment => ({
+    label: segment.title,
+    data: { path: segment.path }
+  }));
+}
+
+const navigate = (data) => (event) => {
+  goto(data.path);
+};
+</script>
+
+<Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
+```
+
+### React Router Integration
+
+```javascript
+// For reference - similar pattern can be adapted
+const breadcrumbs = useBreadcrumbs(routes);
+```
+
+## Best Practices
+
+1. **Clear Hierarchy**: Ensure breadcrumbs reflect a logical hierarchy
+2. **Consistent Naming**: Use consistent labeling across similar pages
+3. **Responsive Design**: Consider how breadcrumbs appear on mobile devices
+4. **Performance**: Don't over-nest breadcrumb levels
+5. **User Context**: Show relevant path based on user's entry point
+6. **Skip Navigation**: Provide skip links for accessibility
+
+## Mobile Considerations
+
+For mobile devices, consider:
+
+```css
+@media (max-width: 480px) {
+  .uniface-breadcrumbs {
+    overflow-x: auto;
+    white-space: nowrap;
+  }
+  
+  /* Or show only parent and current */
+  .breadcrumb:not(:nth-last-child(2)):not(:last-child) {
+    display: none;
+  }
+}
+```
+
+## Testing
+
+When testing breadcrumbs:
+
+```javascript
+// Test navigation
+const breadcrumbs = [
+  { label: 'Home', data: { path: '/' } },
+  { label: 'Products', data: { path: '/products' } }
+];
+
+const mockNavigate = vi.fn();
+render(Breadcrumbs, { 
+  props: { items: breadcrumbs, onItemClick: mockNavigate } 
+});
+
+// Click first breadcrumb
+fireEvent.click(screen.getByText('Home'));
+expect(mockNavigate).toHaveBeenCalledWith({ path: '/' });
+```