@pol-studios/features 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,329 @@
+# @pol-studios/features
+
+> Feature modules for POL applications
+
+Business feature modules that encapsulate common application patterns including comments, ordering, punch-lists, and filter utilities. Built on top of `@pol-studios/db` and `@pol-studios/auth`.
+
+## Installation
+
+```bash
+pnpm add @pol-studios/features
+```
+
+## Peer Dependencies
+
+```bash
+pnpm add react @pol-studios/db @pol-studios/auth @pol-studios/utils
+```
+
+## Quick Start
+
+```tsx
+import { CommentProvider, useComments } from "@pol-studios/features/comments";
+import { useOrderManager } from "@pol-studios/features/ordering";
+import { usePunchListPage } from "@pol-studios/features/punch-list";
+import { FilterProvider, useFilterContext } from "@pol-studios/features/filter-utils";
+
+// Comments on any entity
+function ProjectComments({ projectId }) {
+  return (
+    <CommentProvider entityType="project" entityId={projectId}>
+      <CommentList />
+    </CommentProvider>
+  );
+}
+
+// Drag-and-drop ordering
+function TaskList({ tasks }) {
+  const { items, moveItem, saveOrder } = useOrderManager(tasks);
+  // ... render sortable list
+}
+```
+
+## Subpath Exports
+
+| Path | Description |
+|------|-------------|
+| `@pol-studios/features` | All exports combined |
+| `@pol-studios/features/comments` | Comment system for entities |
+| `@pol-studios/features/ordering` | Drag-and-drop ordering utilities |
+| `@pol-studios/features/punch-list` | Punch-list / checklist functionality |
+| `@pol-studios/features/filter-utils` | Filter builder utilities |
+
+## API Reference
+
+### Comments Module
+
+Provides a complete comment system with reactions, read tracking, and quotes.
+
+```tsx
+import {
+  CommentProvider,
+  useComments,
+  CommentContext,
+} from "@pol-studios/features/comments";
+
+import type {
+  CommentContextType,
+  CommentWithRelations,
+  Quote,
+  ProfileRow,
+  CoreCommentRow,
+  CoreCommentReactionRow,
+  CoreCommentReadRow,
+  CommentProviderProps,
+} from "@pol-studios/features/comments";
+
+// Wrap component with CommentProvider
+<CommentProvider
+  entityType="project"
+  entityId={projectId}
+  userId={currentUserId}
+>
+  <CommentSection />
+</CommentProvider>
+
+// Use comments in child components
+function CommentSection() {
+  const {
+    comments,           // All comments with relations
+    isLoading,          // Loading state
+    addComment,         // Add new comment
+    updateComment,      // Edit comment
+    deleteComment,      // Remove comment
+    addReaction,        // React to comment
+    removeReaction,     // Remove reaction
+    markAsRead,         // Mark comment as read
+    replyTo,            // Reply to specific comment
+    quote,              // Quote text from comment
+    unreadCount,        // Number of unread comments
+  } = useComments();
+
+  const handleSubmit = (text: string) => {
+    addComment({ text, parentId: null });
+  };
+
+  return (
+    <div>
+      <div>Unread: {unreadCount}</div>
+      {comments.map(comment => (
+        <Comment
+          key={comment.id}
+          comment={comment}
+          onReply={() => replyTo(comment.id)}
+          onReact={(emoji) => addReaction(comment.id, emoji)}
+        />
+      ))}
+      <CommentInput onSubmit={handleSubmit} />
+    </div>
+  );
+}
+```
+
+### Ordering Module
+
+Utilities for managing item order with optimistic updates.
+
+```tsx
+import {
+  useOrderHint,
+  useOrderManager,
+} from "@pol-studios/features/ordering";
+
+// Generate order hints for positioning
+function useOrderHintExample() {
+  const { generateHint, getHintBetween } = useOrderHint();
+
+  // Get hint for inserting at position
+  const hint = generateHint(index, items);
+
+  // Get hint between two items
+  const betweenHint = getHintBetween(itemA.order_hint, itemB.order_hint);
+}
+
+// Full order management
+function SortableList({ initialItems }) {
+  const {
+    items,              // Ordered items
+    moveItem,           // Move item to new position
+    reorder,            // Reorder by drag-and-drop result
+    saveOrder,          // Persist order to database
+    isDirty,            // Has unsaved changes
+    isLoading,          // Saving in progress
+  } = useOrderManager(initialItems, {
+    table: "tasks",
+    orderColumn: "order_hint",
+  });
+
+  const handleDragEnd = (result) => {
+    if (!result.destination) return;
+    reorder(result.source.index, result.destination.index);
+  };
+
+  return (
+    <DragDropContext onDragEnd={handleDragEnd}>
+      <Droppable droppableId="list">
+        {(provided) => (
+          <div ref={provided.innerRef} {...provided.droppableProps}>
+            {items.map((item, index) => (
+              <Draggable key={item.id} draggableId={item.id} index={index}>
+                {(provided) => <Item item={item} provided={provided} />}
+              </Draggable>
+            ))}
+            {provided.placeholder}
+          </div>
+        )}
+      </Droppable>
+      <button onClick={saveOrder} disabled={!isDirty || isLoading}>
+        Save Order
+      </button>
+    </DragDropContext>
+  );
+}
+```
+
+### Punch-List Module
+
+Punch-list / checklist page functionality for tracking items.
+
+```tsx
+import { usePunchListPage } from "@pol-studios/features/punch-list";
+
+function PunchListPage({ projectId }) {
+  const {
+    items,              // Punch-list items
+    isLoading,          // Loading state
+    filter,             // Current filter
+    setFilter,          // Update filter
+    stats,              // Completion statistics
+    addItem,            // Add new item
+    updateItem,         // Update item
+    deleteItem,         // Remove item
+    toggleComplete,     // Toggle item completion
+    assignTo,           // Assign item to user
+    groupBy,            // Grouped items (by status, assignee, etc.)
+  } = usePunchListPage({
+    projectId,
+    defaultFilter: { status: "open" },
+  });
+
+  return (
+    <div>
+      <Stats total={stats.total} completed={stats.completed} />
+      <FilterBar filter={filter} onChange={setFilter} />
+      <ItemList
+        items={items}
+        onToggle={toggleComplete}
+        onEdit={updateItem}
+        onDelete={deleteItem}
+      />
+      <AddItemForm onAdd={addItem} />
+    </div>
+  );
+}
+```
+
+### Filter Utils Module
+
+Utilities for building dynamic filter UIs.
+
+```tsx
+import {
+  FilterProvider,
+  useFilterContext,
+  useNestedFilterOptions,
+  hookOnChange,
+  getDefaultValue,
+  getComparisonOptions,
+  getDefaultCondition,
+  genId,
+  getPropertyKey,
+  recurseToProperty,
+  getProperty,
+} from "@pol-studios/features/filter-utils";
+
+// Wrap filter UI with provider
+function FilterableList({ data, fields }) {
+  return (
+    <FilterProvider fields={fields}>
+      <FilterBar />
+      <DataList data={data} />
+    </FilterProvider>
+  );
+}
+
+// Build filter UI
+function FilterBar() {
+  const {
+    filters,            // Current filter conditions
+    addFilter,          // Add new filter condition
+    removeFilter,       // Remove filter condition
+    updateFilter,       // Update filter value
+    clearFilters,       // Clear all filters
+    applyFilters,       // Apply filters to data
+    fields,             // Available fields to filter
+  } = useFilterContext();
+
+  return (
+    <div>
+      {filters.map((filter) => (
+        <FilterRow
+          key={filter.id}
+          filter={filter}
+          fields={fields}
+          onUpdate={(updates) => updateFilter(filter.id, updates)}
+          onRemove={() => removeFilter(filter.id)}
+        />
+      ))}
+      <button onClick={addFilter}>Add Filter</button>
+      <button onClick={clearFilters}>Clear</button>
+    </div>
+  );
+}
+
+// Nested filter options (for hierarchical data)
+function CategoryFilter({ categories }) {
+  const options = useNestedFilterOptions(categories, {
+    labelKey: "name",
+    valueKey: "id",
+    childrenKey: "subcategories",
+  });
+
+  return <Select options={options} />;
+}
+
+// Utility functions
+const comparisonOptions = getComparisonOptions("string"); // ["equals", "contains", "startsWith", ...]
+const defaultValue = getDefaultValue("number"); // 0
+const defaultCondition = getDefaultCondition("date"); // { operator: "equals", value: null }
+const id = genId(); // Unique filter ID
+const key = getPropertyKey(field); // Normalized property key
+const value = getProperty(obj, "nested.path"); // Get nested value
+```
+
+## TypeScript Types
+
+```tsx
+import type {
+  // Comments types
+  CommentContextType,
+  CommentWithRelations,
+  Quote,
+  ProfileRow,
+  CoreCommentRow,
+  CoreCommentReactionRow,
+  CoreCommentReadRow,
+  CommentProviderProps,
+} from "@pol-studios/features/comments";
+```
+
+## Related Packages
+
+- [@pol-studios/db](../db) - Database layer (required peer dependency)
+- [@pol-studios/auth](../auth) - Authentication (required peer dependency)
+- [@pol-studios/utils](../utils) - Utility functions (required peer dependency)
+- [@pol-studios/ui](../ui) - UI components for rendering features
+
+## License
+
+UNLICENSED

package/dist/comments/index.js

@@ -14,7 +14,7 @@ import {
   useDbUpsert,
   useSupabase
 } from "@pol-studios/db";
-import { useAuth } from "@pol-studios/auth";
+import { useAuth } from "@pol-studios/db/auth";
 import { isUsable } from "@pol-studios/utils";
 import { Comment } from "@pol-studios/db";
 import { jsx } from "react/jsx-runtime";

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   useDbUpsert,
   useSupabase
 } from "@pol-studios/db";
-import { useAuth } from "@pol-studios/auth";
+import { useAuth } from "@pol-studios/db/auth";
 import { isUsable } from "@pol-studios/utils";
 import { Comment } from "@pol-studios/db";
 import { jsx } from "react/jsx-runtime";
@@ -450,7 +450,7 @@ import {
 } from "@pol-studios/db";
 import { useEffect as useEffect2, useState as useState3 } from "react";
 import { useDbUpsert as useDbUpsert3 } from "@pol-studios/db";
-import { useAuth as useAuth2 } from "@pol-studios/auth";
+import { useAuth as useAuth2 } from "@pol-studios/db/auth";
 function usePunchListPage(relation, entityId) {
   const supabase = useSupabase3();
   const upsert = useDbUpsert3("PunchListPage", ["id"]);

package/dist/punch-list/index.js

@@ -4,7 +4,7 @@ import {
 } from "@pol-studios/db";
 import { useEffect, useState } from "react";
 import { useDbUpsert } from "@pol-studios/db";
-import { useAuth } from "@pol-studios/auth";
+import { useAuth } from "@pol-studios/db/auth";
 function usePunchListPage(relation, entityId) {
   const supabase = useSupabase();
   const upsert = useDbUpsert("PunchListPage", ["id"]);

package/package.json

@@ -1,26 +1,42 @@
 {
   "name": "@pol-studios/features",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Feature modules for POL applications",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "exports": {
-    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
-    "./comments": { "import": "./dist/comments/index.js", "types": "./dist/comments/index.d.ts" },
-    "./ordering": { "import": "./dist/ordering/index.js", "types": "./dist/ordering/index.d.ts" },
-    "./punch-list": { "import": "./dist/punch-list/index.js", "types": "./dist/punch-list/index.d.ts" },
-    "./filter-utils": { "import": "./dist/filter-utils/index.js", "types": "./dist/filter-utils/index.d.ts" }
-  },
-  "keywords": ["features", "comments", "ordering", "punch-list"],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./comments": {
+      "import": "./dist/comments/index.js",
+      "types": "./dist/comments/index.d.ts"
+    },
+    "./ordering": {
+      "import": "./dist/ordering/index.js",
+      "types": "./dist/ordering/index.d.ts"
+    },
+    "./punch-list": {
+      "import": "./dist/punch-list/index.js",
+      "types": "./dist/punch-list/index.d.ts"
+    },
+    "./filter-utils": {
+      "import": "./dist/filter-utils/index.js",
+      "types": "./dist/filter-utils/index.d.ts"
+    }
   },
+  "keywords": [
+    "features",
+    "comments",
+    "ordering",
+    "punch-list"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -29,15 +45,18 @@
   },
   "peerDependencies": {
     "@pol-studios/db": ">=1.0.0",
-    "@pol-studios/auth": ">=1.0.0",
     "@pol-studios/utils": ">=1.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@pol-studios/db": "workspace:*",
-    "@pol-studios/auth": "workspace:*",
-    "@pol-studios/utils": "workspace:*",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@pol-studios/db": "1.0.1",
+    "@pol-studios/utils": "1.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
   }
-}
+}