@pindoba/astro-tree-view 0.0.0-alpha-20250910225440

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright 2025 Eduardo Lopes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# Tree View Component
+
+A flexible and accessible tree view component for Astro applications.
+
+## Features
+
+- ✅ Collapsible/expandable tree nodes
+- ✅ Selectable items with keyboard navigation
+- ✅ Customizable styling with variants and sizes
+- ✅ Accessible with proper ARIA attributes
+- ✅ TypeScript support
+- ✅ Custom icons support
+- ✅ Event handling for selection
+
+## Installation
+
+```bash
+npm install @pindoba/ui-astro-tree-view @pindoba/styles-tree-view
+```
+
+## Basic Usage
+
+```astro
+---
+import { TreeView, TreeViewItem } from "@pindoba/ui-astro-tree-view";
+---
+
+<TreeView>
+  <TreeViewItem label="Giant planets" collapsible defaultOpen>
+    <TreeViewItem slot="children" label="Gas giants" collapsible>
+      <TreeViewItem slot="children" label="Jupiter" />
+      <TreeViewItem slot="children" label="Saturn" />
+    </TreeViewItem>
+    <TreeViewItem slot="children" label="Ice giants" collapsible>
+      <TreeViewItem slot="children" label="Uranus" />
+      <TreeViewItem slot="children" label="Neptune" />
+    </TreeViewItem>
+  </TreeViewItem>
+</TreeView>
+```
+
+## Props
+
+### TreeView
+
+| Prop          | Type                                | Default     | Description              |
+| ------------- | ----------------------------------- | ----------- | ------------------------ |
+| `size`        | `"sm" \| "md" \| "lg"`              | `"md"`      | Size variant of the tree |
+| `variant`     | `"default" \| "subtle" \| "ghost"`  | `"default"` | Visual variant           |
+| `passThrough` | `Record<string, SystemStyleObject>` | -           | Custom styles for slots  |
+
+### TreeViewItem
+
+| Prop          | Type                                | Default     | Description                                              |
+| ------------- | ----------------------------------- | ----------- | -------------------------------------------------------- |
+| `label`       | `string`                            | -           | The text content for this tree item                      |
+| `collapsible` | `boolean`                           | `false`     | Whether this item has children and should be collapsible |
+| `defaultOpen` | `boolean`                           | `false`     | Whether the item is expanded by default                  |
+| `selectable`  | `boolean`                           | `false`     | Whether this item is selectable                          |
+| `selected`    | `boolean`                           | `false`     | Whether this item is currently selected                  |
+| `icon`        | `string`                            | -           | Icon HTML to display before the label                    |
+| `size`        | `"sm" \| "md" \| "lg"`              | `"md"`      | Size variant                                             |
+| `variant`     | `"default" \| "subtle" \| "ghost"`  | `"default"` | Visual variant                                           |
+| `passThrough` | `Record<string, SystemStyleObject>` | -           | Custom styles for slots                                  |
+
+## Examples
+
+### With Selection
+
+```astro
+<TreeView>
+  <TreeViewItem label="Documents" collapsible defaultOpen selectable>
+    <TreeViewItem slot="children" label="resume.pdf" selectable selected />
+    <TreeViewItem slot="children" label="cover-letter.pdf" selectable />
+  </TreeViewItem>
+</TreeView>
+```
+
+### With Icons
+
+```astro
+<TreeView>
+  <TreeViewItem label="Folder" collapsible icon="<svg>...</svg>">
+    <TreeViewItem slot="children" label="file.txt" icon="<svg>...</svg>" />
+  </TreeViewItem>
+</TreeView>
+```
+
+### Different Sizes and Variants
+
+```astro
+<!-- Small subtle tree -->
+<TreeView size="sm" variant="subtle">
+  <TreeViewItem label="Small item" />
+</TreeView>
+
+<!-- Large ghost tree -->
+<TreeView size="lg" variant="ghost">
+  <TreeViewItem label="Large item" />
+</TreeView>
+```
+
+## Events
+
+### tree-item-select
+
+Fired when a selectable tree item is clicked or activated with keyboard.
+
+```javascript
+document.addEventListener("tree-item-select", (event) => {
+  console.log("Selected item:", event.detail.label);
+  console.log("Item element:", event.detail.element);
+});
+```
+
+## Accessibility
+
+- Keyboard navigation with Enter and Space for selection
+- Proper focus management with visible focus indicators
+- ARIA attributes for screen readers
+- Semantic HTML with `details`/`summary` for collapsible items
+
+## Styling
+
+The component uses CSS-in-JS with Panda CSS. You can customize styles using the `passThrough` prop:
+
+```astro
+<TreeView
+  passThrough={{
+    root: { backgroundColor: "gray.50" },
+    item: { borderRadius: "lg" },
+  }}
+>
+  <!-- ... -->
+</TreeView>
+```

package/index.ts

@@ -0,0 +1,11 @@
+// Do not write code directly here, instead use the `src` folder!
+// Then, use this file to export everything you want your user to access.
+
+import TreeView from "./src/TreeView.astro";
+import TreeViewItem from "./src/TreeViewItem.astro";
+
+export * from "./src/TreeView.astro";
+export * from "./src/TreeViewItem.astro";
+export * from "./src/tree-utils";
+
+export { TreeView, TreeViewItem };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pindoba/astro-tree-view",
+  "version": "0.0.0-alpha-20250910225440",
+  "homepage": "https://github.com/EduardoLopes/pindoba/tree/main/packages/ui/astro/tree-view#README.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EduardoLopes/pindoba.git",
+    "directory": "packages/ui/astro/tree-view"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "src",
+    "index.ts"
+  ],
+  "keywords": [
+    "astro-component",
+    "tree-view",
+    "navigation"
+  ],
+  "devDependencies": {
+    "@astrojs/check": "^0.9.4",
+    "astro": "^5.13.7",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0"
+  },
+  "dependencies": {
+    "@pindoba/panda": "0.0.0-alpha-20250910225440",
+    "@pindoba/utils": "0.0.0-alpha-20250910225440",
+    "@pindoba/styles-tree-view": "0.0.0-alpha-20250910225440"
+  },
+  "scripts": {
+    "lint": "TIMING=1 eslint . --max-warnings 0",
+    "lint:fix": "TIMING=1 eslint . --fix --max-warnings 0",
+    "format": "prettier --write .",
+    "format:fix": "prettier --write .",
+    "link": "pnpm link",
+    "unlink": "pnpm unlink",
+    "check": "astro check",
+    "dev": "astro check --watch",
+    "clean": "rm -rf .astro && rm -rf node_modules && rm -rf .turbo"
+  }
+}

package/src/TreeNodeItem.astro

@@ -0,0 +1,57 @@
+---
+import { type TreeNode, type TreeState, TreeUtils } from "./tree-utils";
+import {
+  type TreeViewStyleProps,
+  type TreeViewSlots,
+} from "@pindoba/styles-tree-view";
+import type { SystemStyleObject } from "@pindoba/panda/types";
+import TreeViewItem from "./TreeViewItem.astro";
+
+export interface TreeNodeItemProps {
+  node: TreeNode;
+  state: TreeState;
+  size?: TreeViewStyleProps["size"];
+  emphasis?: TreeViewStyleProps["emphasis"];
+  passThrough?: { [key in TreeViewSlots]?: SystemStyleObject };
+}
+
+type Props = TreeNodeItemProps;
+
+const { node, state, size, emphasis, passThrough } = Astro.props;
+
+const isExpanded = TreeUtils.isExpanded(state, node.id);
+const hasChildren = node.children && node.children.length > 0;
+---
+
+{
+  hasChildren ? (
+    <TreeViewItem
+      label={node.label}
+      open={isExpanded}
+      size={size}
+      emphasis={emphasis}
+      passThrough={passThrough}
+      data-node-id={node.id}
+    >
+      {node.children &&
+        node.children.map((childNode) => (
+          <Astro.self
+            slot="children"
+            node={childNode}
+            state={state}
+            size={size}
+            emphasis={emphasis}
+            passThrough={passThrough}
+          />
+        ))}
+    </TreeViewItem>
+  ) : (
+    <TreeViewItem
+      label={node.label}
+      size={size}
+      emphasis={emphasis}
+      passThrough={passThrough}
+      data-node-id={node.id}
+    />
+  )
+}

package/src/TreeView.astro

@@ -0,0 +1,95 @@
+---
+import { css, cx } from "@pindoba/panda/css";
+import {
+  treeViewStyles,
+  type TreeViewSlots,
+  type TreeViewStyleProps,
+} from "@pindoba/styles-tree-view";
+import { type TreeNode, type TreeState, TreeUtils } from "./tree-utils";
+import type { HTMLAttributes } from "astro/types";
+import type { SystemStyleObject } from "@pindoba/panda/types";
+import TreeNodeItem from "./TreeNodeItem.astro";
+
+export interface TreeViewProps extends HTMLAttributes<"ul"> {
+  size?: TreeViewStyleProps["size"];
+  emphasis?: TreeViewStyleProps["emphasis"];
+  passThrough?: { [key in TreeViewSlots]?: SystemStyleObject };
+  // Imperative API props
+  data?: TreeNode[];
+  onToggle?: (nodeId: string, expanded: boolean) => void;
+}
+
+type Props = TreeViewProps;
+
+const {
+  class: className,
+  size = "md",
+  emphasis = "default",
+  passThrough,
+  data,
+  onToggle,
+  ...props
+} = Astro.props;
+
+const classes = treeViewStyles.raw({ size, emphasis });
+
+// Initialize state for imperative API
+let treeState: TreeState | undefined;
+if (data) {
+  treeState = TreeUtils.getInitialState(data);
+}
+---
+
+<ul
+  class={cx(css(classes.root, passThrough?.root), className)}
+  data-tree-view-root
+  {...props}
+>
+  {
+    data && treeState ? (
+      data.map((node: TreeNode) => (
+        <TreeNodeItem
+          node={node}
+          state={treeState!}
+          size={size}
+          emphasis={emphasis}
+          passThrough={passThrough}
+        />
+      ))
+    ) : (
+      <slot />
+    )
+  }
+</ul>
+
+<script
+  is:inline
+  define:vars={{ onToggleStr: onToggle?.toString(), hasData: !!data }}
+>
+  // Add event handling for toggle interactions in imperative mode
+  if (hasData && onToggleStr) {
+    document.addEventListener("DOMContentLoaded", () => {
+      const treeRoot = document.querySelector("[data-tree-view-root]");
+
+      if (treeRoot) {
+        treeRoot.addEventListener("click", (event) => {
+          const target = event.target.closest("[data-node-id]");
+          if (target) {
+            const trigger = event.target.closest("summary");
+            if (trigger) {
+              const nodeId = target.getAttribute("data-node-id");
+              const details = trigger.parentElement;
+              const isExpanding = !details.hasAttribute("open");
+
+              // Dispatch custom event instead of direct function call
+              const toggleEvent = new CustomEvent("tree-node-toggle", {
+                detail: { nodeId, expanded: isExpanding },
+              });
+              document.dispatchEvent(toggleEvent);
+            }
+          }
+        });
+      }
+    });
+  }
+</script>

package/src/TreeViewItem.astro

@@ -0,0 +1,130 @@
+---
+import { css, cx } from "@pindoba/panda/css";
+import {
+  treeViewStyles,
+  type TreeViewSlots,
+  type TreeViewStyleProps,
+} from "@pindoba/styles-tree-view";
+import type { HTMLAttributes } from "astro/types";
+import type { SystemStyleObject } from "@pindoba/panda/types";
+
+export interface TreeViewItemProps extends HTMLAttributes<"li"> {
+  label?: string;
+  open?: boolean;
+  size?: TreeViewStyleProps["size"];
+  emphasis?: TreeViewStyleProps["emphasis"];
+  passThrough?: { [key in TreeViewSlots]?: SystemStyleObject };
+}
+
+type Props = TreeViewItemProps;
+
+const {
+  class: className,
+  label,
+  open = false,
+  size,
+  emphasis,
+  passThrough,
+  ...props
+} = Astro.props;
+
+const classes = treeViewStyles.raw({ size, emphasis });
+const hasChildren = Astro.slots.has("children");
+const hasLabel = Astro.slots.has("label");
+const hasLeadingElement = Astro.slots.has("leadingElement");
+const hasTrailingElement = Astro.slots.has("trailingElement");
+const displayLabel = hasLabel ? null : label;
+---
+
+<li class={cx(css(classes.item, passThrough?.item), className)} {...props}>
+  {
+    hasChildren ? (
+      <details open={open}>
+        <summary
+          class={cx(
+            "tree-view-summary",
+            css(classes.summary, passThrough?.summary),
+          )}
+        >
+          <span
+            class={cx(
+              "tree-view-trigger",
+              css(classes.trigger, passThrough?.trigger),
+            )}
+          >
+            <svg
+              class={cx("tree-view-icon", css(classes.icon, passThrough?.icon))}
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            >
+              <path d="m9 18 6-6-6-6" />
+            </svg>
+          </span>
+
+          {hasLeadingElement && (
+            <div
+              class={cx(
+                "tree-view-leading-element",
+                css(classes.leadingElement, passThrough?.leadingElement),
+              )}
+            >
+              <slot name="leadingElement" />
+            </div>
+          )}
+
+          <span class={css(classes.label, passThrough?.label)}>
+            {hasLabel ? <slot name="label" /> : displayLabel}
+          </span>
+          {hasTrailingElement && (
+            <div
+              class={cx(
+                "tree-view-trailing-element",
+                css(classes.trailingElement, passThrough?.trailingElement),
+              )}
+            >
+              <slot name="trailingElement" />
+            </div>
+          )}
+        </summary>
+        <ul class={css(classes.children, passThrough?.children)}>
+          <slot name="children" />
+        </ul>
+      </details>
+    ) : (
+      <div
+        class={cx(
+          "tree-view-summary",
+          css(classes.summary, passThrough?.summary),
+        )}
+      >
+        {hasLeadingElement && (
+          <div
+            class={cx(
+              "tree-view-leading-element",
+              css(classes.leadingElement, passThrough?.leadingElement),
+            )}
+          >
+            <slot name="leadingElement" />
+          </div>
+        )}
+        <span class={css(classes.label, passThrough?.label)}>
+          {hasLabel ? <slot name="label" /> : displayLabel}
+        </span>
+        {hasTrailingElement && (
+          <div
+            class={cx(
+              "tree-view-trailing-element",
+              css(classes.trailingElement, passThrough?.trailingElement),
+            )}
+          >
+            <slot name="trailingElement" />
+          </div>
+        )}
+      </div>
+    )
+  }
+</li>

package/src/tree-utils.ts

@@ -0,0 +1,54 @@
+// Tree data structure interfaces
+export interface TreeNode {
+  id: string;
+  label: string;
+  expanded?: boolean;
+  children?: TreeNode[];
+}
+
+export interface TreeState {
+  expandedNodes: Set<string>;
+}
+
+// Tree manipulation utilities
+export class TreeUtils {
+  static expandNode(state: TreeState, nodeId: string): TreeState {
+    const newExpandedNodes = new Set(state.expandedNodes);
+    newExpandedNodes.add(nodeId);
+    return { expandedNodes: newExpandedNodes };
+  }
+
+  static collapseNode(state: TreeState, nodeId: string): TreeState {
+    const newExpandedNodes = new Set(state.expandedNodes);
+    newExpandedNodes.delete(nodeId);
+    return { expandedNodes: newExpandedNodes };
+  }
+
+  static toggleNode(state: TreeState, nodeId: string): TreeState {
+    return state.expandedNodes.has(nodeId)
+      ? this.collapseNode(state, nodeId)
+      : this.expandNode(state, nodeId);
+  }
+
+  static isExpanded(state: TreeState, nodeId: string): boolean {
+    return state.expandedNodes.has(nodeId);
+  }
+
+  static getInitialState(data: TreeNode[]): TreeState {
+    const expandedNodes = new Set<string>();
+
+    const collectExpanded = (nodes: TreeNode[]) => {
+      nodes.forEach((node) => {
+        if (node.expanded) {
+          expandedNodes.add(node.id);
+        }
+        if (node.children) {
+          collectExpanded(node.children);
+        }
+      });
+    };
+
+    collectExpanded(data);
+    return { expandedNodes };
+  }
+}