@alexbrand09/famtreejs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,259 @@
+# @alexbrand09/famtreejs
+
+[![npm version](https://img.shields.io/npm/v/@alexbrand09/famtreejs.svg)](https://www.npmjs.com/package/@alexbrand09/famtreejs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A React library for rendering interactive family trees with a partnership-centric data model. Unlike traditional family tree libraries where children belong to a single parent, this library treats partnerships (marriages, unions) as first-class entities, with children descending from partnerships rather than individuals.
+
+## Features
+
+- **Partnership-centric data model** - Children belong to partnerships, not individuals
+- **Multiple orientations** - Top-down, bottom-up, left-right, right-left layouts
+- **Interactive** - Pan, zoom, click, hover, expand/collapse branches
+- **Keyboard accessible** - Full keyboard navigation with ARIA support
+- **Themeable** - Light/dark themes with CSS variables for customization
+- **Animated** - Smooth transitions with Framer Motion, respects `prefers-reduced-motion`
+- **TypeScript** - Full type safety with generics for custom data
+
+## Installation
+
+```bash
+npm install @alexbrand09/famtreejs
+```
+
+## Quick Start
+
+```tsx
+import { FamilyTree, BasicPersonCard } from '@alexbrand09/famtreejs';
+import '@alexbrand09/famtreejs/styles.css';
+import type { FamilyTreeData } from '@alexbrand09/famtreejs';
+
+const data: FamilyTreeData<{ name: string }> = {
+  people: [
+    { id: 'p1', data: { name: 'John' } },
+    { id: 'p2', data: { name: 'Mary' } },
+    { id: 'c1', data: { name: 'Alice' } },
+  ],
+  partnerships: [
+    { id: 'u1', partnerIds: ['p1', 'p2'], childIds: ['c1'] }
+  ],
+};
+
+function App() {
+  return (
+    <div style={{ width: '100%', height: '600px' }}>
+      <FamilyTree
+        data={data}
+        nodeComponent={BasicPersonCard}
+        onPersonClick={(id, data) => console.log('Clicked:', id, data)}
+      />
+    </div>
+  );
+}
+```
+
+## Data Model
+
+### PersonNode
+
+```typescript
+interface PersonNode<T = unknown> {
+  id: string;      // Unique identifier
+  data: T;         // Your custom data (passed to nodeComponent)
+}
+```
+
+### Partnership
+
+```typescript
+interface Partnership {
+  id: string;
+  partnerIds: [string, string | null];  // [partner1, partner2] or [parent, null] for single parent
+  childIds: string[];                    // Children from this partnership
+  type?: 'marriage' | 'civil-union' | 'partnership' | 'other';
+}
+```
+
+### FamilyTreeData
+
+```typescript
+interface FamilyTreeData<T = unknown> {
+  people: PersonNode<T>[];
+  partnerships: Partnership[];
+  rootPersonId?: string;  // Optional starting point
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `FamilyTreeData<T>` | required | The family tree data |
+| `nodeComponent` | `ComponentType<NodeComponentProps<T>>` | required | Component to render each person |
+| `orientation` | `'top-down' \| 'bottom-up' \| 'left-right' \| 'right-left'` | `'top-down'` | Tree layout direction |
+| `theme` | `'light' \| 'dark'` | `'light'` | Built-in theme |
+| `spacing` | `SpacingConfig` | `{ generation: 120, siblings: 60, partners: 40 }` | Spacing between nodes |
+| `lineStyle` | `LineStyle` | - | Custom line styling |
+| `initialZoom` | `number` | `1` | Initial zoom level |
+| `minZoom` | `number` | `0.1` | Minimum zoom level |
+| `maxZoom` | `number` | `3` | Maximum zoom level |
+| `disableAnimations` | `boolean` | `false` | Disable all animations |
+| `animationDuration` | `number` | `300` | Animation duration in ms |
+| `onPersonClick` | `(id: string, data: T) => void` | - | Called when a person is clicked |
+| `onPersonHover` | `(id: string \| null, data: T \| null) => void` | - | Called on hover |
+| `onPartnershipClick` | `(id: string) => void` | - | Called when a partnership line is clicked |
+| `onZoomChange` | `(zoom: number) => void` | - | Called when zoom changes |
+
+## Custom Node Components
+
+Create your own node component by implementing `NodeComponentProps`:
+
+```tsx
+import type { NodeComponentProps } from '@alexbrand09/famtreejs';
+
+interface MyPersonData {
+  name: string;
+  birthYear?: number;
+  photoUrl?: string;
+}
+
+function MyPersonCard({ data, isSelected, isHovered, isExpanded, onToggleExpand }: NodeComponentProps<MyPersonData>) {
+  return (
+    <div style={{
+      padding: '10px',
+      border: isSelected ? '2px solid blue' : '1px solid gray',
+      backgroundColor: isHovered ? '#f0f0f0' : 'white',
+    }}>
+      {data.photoUrl && <img src={data.photoUrl} alt={data.name} />}
+      <div>{data.name}</div>
+      {data.birthYear && <div>Born: {data.birthYear}</div>}
+      <button onClick={onToggleExpand}>
+        {isExpanded ? 'Collapse' : 'Expand'}
+      </button>
+    </div>
+  );
+}
+```
+
+## Built-in Components
+
+### BasicPersonCard
+
+Simple card showing just the name:
+
+```tsx
+import { BasicPersonCard } from '@alexbrand09/famtreejs';
+```
+
+### DetailedPersonCard
+
+Card with photo, name, and dates:
+
+```tsx
+import { DetailedPersonCard } from '@alexbrand09/famtreejs';
+
+// Data should include: name, birthDate?, deathDate?, photoUrl?
+```
+
+## Ref API
+
+Access imperative methods via ref:
+
+```tsx
+import { useRef } from 'react';
+import { FamilyTree } from '@alexbrand09/famtreejs';
+import type { FamilyTreeHandle } from '@alexbrand09/famtreejs';
+
+function App() {
+  const treeRef = useRef<FamilyTreeHandle>(null);
+
+  return (
+    <>
+      <button onClick={() => treeRef.current?.zoomIn()}>Zoom In</button>
+      <button onClick={() => treeRef.current?.fitToView()}>Fit</button>
+      <FamilyTree ref={treeRef} data={data} nodeComponent={BasicPersonCard} />
+    </>
+  );
+}
+```
+
+### Available Methods
+
+- `zoomTo(level: number)` - Set zoom level
+- `zoomIn()` / `zoomOut()` - Zoom by step
+- `centerOnPerson(id: string)` - Center view on a person
+- `fitToView()` - Fit entire tree in view
+- `expandAll()` / `collapseAll()` - Expand/collapse all branches
+- `toggleBranch(id: string)` - Toggle a specific branch
+- `setRoot(id: string)` - Re-root the tree
+- `getZoom()` - Get current zoom level
+- `getRoot()` - Get current root person ID
+
+## Hooks
+
+Use hooks inside the FamilyTree component tree:
+
+```tsx
+import { useFamilyTreeState, useFamilyTreeActions } from '@alexbrand09/famtreejs';
+
+function MyControls() {
+  const { zoomLevel, selectedPersonId } = useFamilyTreeState();
+  const { zoomIn, zoomOut, fitToView } = useFamilyTreeActions();
+
+  return (
+    <div>
+      <span>Zoom: {Math.round(zoomLevel * 100)}%</span>
+      <button onClick={zoomIn}>+</button>
+      <button onClick={zoomOut}>-</button>
+    </div>
+  );
+}
+```
+
+## Theming
+
+### CSS Variables
+
+Customize the appearance using CSS variables:
+
+```css
+.family-tree {
+  --ft-line-color: #333;
+  --ft-line-width: 2px;
+  --ft-node-background: #fff;
+  --ft-node-border: #ddd;
+  --ft-node-text: #333;
+  --ft-node-shadow: rgba(0, 0, 0, 0.1);
+  --ft-node-hover-border: #999;
+  --ft-node-selected-border: #0066cc;
+  --ft-node-selected-shadow: rgba(0, 102, 204, 0.3);
+}
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Arrow keys | Navigate between nodes |
+| Enter / Space | Select focused node |
+| E | Toggle expand/collapse on focused node |
+| + / - | Zoom in / out |
+| 0 | Fit to view |
+| Home / End | Jump to first / last node |
+
+## Accessibility
+
+- ARIA tree structure with `role="tree"` and `role="treeitem"`
+- `aria-selected`, `aria-expanded` states
+- Visible focus indicators
+- Respects `prefers-reduced-motion` media query
+- WCAG AA compliant contrast ratios
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- React 18+
+
+## License
+
+MIT

package/dist/components/FamilyTree.d.ts

@@ -0,0 +1,7 @@
+import type { FamilyTreeProps, FamilyTreeHandle } from '../types';
+import '../styles/theme.css';
+export declare const FamilyTree: <T>(props: FamilyTreeProps<T> & {
+    ref?: React.ForwardedRef<FamilyTreeHandle>;
+}) => React.ReactElement;
+export type { FamilyTreeProps, FamilyTreeHandle };
+//# sourceMappingURL=FamilyTree.d.ts.map

package/dist/components/FamilyTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FamilyTree.d.ts","sourceRoot":"","sources":["../../src/components/FamilyTree.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAsB,MAAM,UAAU,CAAC;AAItF,OAAO,qBAAqB,CAAC;AAszB7B,eAAO,MAAM,UAAU,EAAkC,CAAC,CAAC,EACzD,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAA;CAAE,KACvE,KAAK,CAAC,YAAY,CAAC;AAExB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/components/FamilyTreeWithProvider.d.ts

@@ -0,0 +1,5 @@
+import type { FamilyTreeProps, FamilyTreeHandle } from '../types';
+export declare const FamilyTreeWithProvider: <T>(props: FamilyTreeProps<T> & {
+    ref?: React.ForwardedRef<FamilyTreeHandle>;
+}) => React.ReactElement;
+//# sourceMappingURL=FamilyTreeWithProvider.d.ts.map

package/dist/components/FamilyTreeWithProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FamilyTreeWithProvider.d.ts","sourceRoot":"","sources":["../../src/components/FamilyTreeWithProvider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA2DlE,eAAO,MAAM,sBAAsB,EAA8C,CAAC,CAAC,EACjF,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAA;CAAE,KACvE,KAAK,CAAC,YAAY,CAAC"}

package/dist/components/defaults/BasicPersonCard.d.ts

@@ -0,0 +1,7 @@
+import type { NodeComponentProps } from '../../types';
+interface BasicPersonData {
+    name: string;
+}
+export declare function BasicPersonCard({ data, isSelected, isHovered, }: NodeComponentProps<BasicPersonData>): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=BasicPersonCard.d.ts.map

package/dist/components/defaults/BasicPersonCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicPersonCard.d.ts","sourceRoot":"","sources":["../../../src/components/defaults/BasicPersonCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,eAAe,CAAC,EAC9B,IAAI,EACJ,UAAU,EACV,SAAS,GACV,EAAE,kBAAkB,CAAC,eAAe,CAAC,2CA0BrC"}

package/dist/components/defaults/DetailedPersonCard.d.ts

@@ -0,0 +1,10 @@
+import type { NodeComponentProps } from '../../types';
+interface DetailedPersonData {
+    name: string;
+    birthDate?: string;
+    deathDate?: string;
+    photoUrl?: string;
+}
+export declare function DetailedPersonCard({ data, isSelected, isHovered, }: NodeComponentProps<DetailedPersonData>): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=DetailedPersonCard.d.ts.map

package/dist/components/defaults/DetailedPersonCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DetailedPersonCard.d.ts","sourceRoot":"","sources":["../../../src/components/defaults/DetailedPersonCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,UAAU,EACV,SAAS,GACV,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,2CAyDxC"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useFamilyTreeState, useFamilyTreeActions } from '../store/FamilyTreeContext';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.css

@@ -0,0 +1 @@
+.family-tree{--ft-line-color: #333;--ft-line-width: 2px;--ft-background: transparent;--ft-node-background: #fff;--ft-node-border: #ddd;--ft-node-text: #333;--ft-node-shadow: rgba(0, 0, 0, .1);--ft-node-hover-border: #999;--ft-node-selected-border: #0066cc;--ft-node-selected-shadow: rgba(0, 102, 204, .3)}.family-tree--dark{--ft-line-color: #888;--ft-line-width: 2px;--ft-background: transparent;--ft-node-background: #2a2a2a;--ft-node-border: #444;--ft-node-text: #e0e0e0;--ft-node-shadow: rgba(0, 0, 0, .3);--ft-node-hover-border: #666;--ft-node-selected-border: #4da6ff;--ft-node-selected-shadow: rgba(77, 166, 255, .3)}.family-tree--light{--ft-line-color: #333;--ft-line-width: 2px;--ft-background: transparent;--ft-node-background: #fff;--ft-node-border: #ddd;--ft-node-text: #333;--ft-node-shadow: rgba(0, 0, 0, .1);--ft-node-hover-border: #999;--ft-node-selected-border: #0066cc;--ft-node-selected-shadow: rgba(0, 102, 204, .3)}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { FamilyTreeWithProvider as FamilyTree } from './components/FamilyTreeWithProvider';
+export { FamilyTree as FamilyTreeCore } from './components/FamilyTree';
+export type { FamilyTreeProps, FamilyTreeHandle } from './components/FamilyTree';
+export { useFamilyTreeState, useFamilyTreeActions } from './hooks';
+export { FamilyTreeProvider } from './store/FamilyTreeContext';
+export { BasicPersonCard } from './components/defaults/BasicPersonCard';
+export { DetailedPersonCard } from './components/defaults/DetailedPersonCard';
+export type { PersonNode, Partnership, FamilyTreeData, NodeComponentProps, FamilyTreeState, Orientation, SpacingConfig, LineStyle, Theme, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,IAAI,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAG3F,OAAO,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGvE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGjF,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAG9E,YAAY,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,aAAa,EACb,SAAS,EACT,KAAK,GACN,MAAM,SAAS,CAAC"}