@cooperco/cooper-component-library 0.1.61 → 0.1.62

package/README.md

@@ -1,11 +1,113 @@
-# Vue 3 + Vite
+# Cooper Component Library
 
-This template should help get you started developing with Vue 3 in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+A Vue 3 component library built with TypeScript, Vite, and Tailwind CSS. Published as `@cooperco/cooper-component-library` and designed for integration with Contentful CMS via GraphQL.
+
+## Tech Stack
+
+- **Vue 3.5+** - Composition API with `<script setup>`
+- **TypeScript 5.3+** - Strict mode enabled
+- **Tailwind CSS 3.4+** - Utility-first styling
+- **Vite 5.2+** - Library build mode
+- **Storybook 8.2+** - Component documentation
+- **GraphQL** - Contentful CMS integration
+- **pnpm** - Package manager
 
 ## Recommended IDE Setup
 
 - [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously Volar) and disable Vetur
 
-### TODO issues
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start Storybook dev server
+pnpm run dev
+
+# Run linter
+pnpm run lint
+
+# Fix linting issues
+pnpm run lint:fix
+
+# Type check
+pnpm run check-types
+```
+
+## Testing Locally
+
+To test the component library in a consuming project before publishing:
+
+```bash
+# 1. Build and pack the library
+pnpm run local-test
+```
+
+This creates a `.tgz` file in the root directory (e.g., `cooperco-cooper-component-library-0.1.61.tgz`)
+
+```bash
+# 2. In the consuming project, install the local package
+pnpm add /path/to/cooperco-cooper-component-library-0.1.61.tgz
+```
+
+This allows you to test changes locally before publishing to npm.
+
+## Building and Publishing
+
+The build and publish process needs to happen manually when changes are merged to `main`:
+
+### Workflow
+
+1. **Merge to main** - Merge your feature branch to `main`
+2. **Patch version** - Update version number using `npm version patch` (or `minor`/`major`)
+3. **Publish** - Run `npm publish` to publish to npm registry
+4. **Push** - Push changes and tags to GitHub
+
+### Build Process
+
+When you run `pnpm run build`, the following happens in order:
+
+1. **`build:types`** - Compiles Vue component TypeScript definitions
+2. **`build:cms`** - Compiles GraphQL queries for Contentful
+3. **`vite build`** - Builds the component library bundle
+
+All build artifacts are output to the `dist/` directory.
+
+### Package Exports
+
+The package exports multiple entry points:
+
+- **Components:** `@cooperco/cooper-component-library` - Main component library
+- **Styles:** `@cooperco/cooper-component-library/css/main.css` - Main styles
+- **Theme:** `@cooperco/cooper-component-library/css/theme.css` - Theme variables
+- **Queries:** `@cooperco/cooper-component-library/cms/contentful/graphql` - GraphQL queries
+
+## Project Structure
+
+```
+├── src/
+│   ├── components/          # Vue components
+│   │   ├── ComponentName/
+│   │   │   ├── ComponentName.vue
+│   │   │   └── ComponentName.ts
+│   │   ├── components.ts    # Component exports
+│   │   └── types.ts         # Type exports
+│   ├── config/              # Configuration (color palettes, passthroughs)
+│   └── utils/               # Utility functions
+├── cms/
+│   └── contentful/
+│       └── queries/         # GraphQL queries (see cms/contentful/queries/README.md)
+├── .storybook/              # Storybook configuration
+│   └── components/          # Component stories
+└── dist/                    # Build output (generated)
+```
+
+## Documentation
+
+- **Component Documentation:** Run `pnpm run dev` to view Storybook
+- **GraphQL Queries:** See [cms/contentful/queries/README.md](cms/contentful/queries/README.md)
+
+## TODO Issues
 
-- There are many places where `class` is not recognized by Typescript. Examples are "start"/"end" in ContainerModule. This is because we are not defining `class` on the component types. Defining them explicitly overrides the default Attribute Inheritance behavior of Vue. Need to find a way to get around this
+- There are many places where `class` is not recognized by TypeScript. Examples are "start"/"end" in ContainerModule. This is because we are not defining `class` on the component types. Defining them explicitly overrides the default Attribute Inheritance behavior of Vue. Need to find a way to get around this

package/dist/cms/README.md

@@ -1,42 +1,112 @@
-# Migrations
+# GraphQL Queries
 
-## Prerequisites
+This directory contains GraphQL queries for fetching content from Contentful CMS.
 
-- Run `pnpm install`
-- Obtain a Contentful CMA token
-- Confirm and double check what space and environment you should be running these in
-- Run `pnpm exec contentful-cli-migrations --environment-id <your-env-name> --space-id <space-id> --management-token <CMA-TOKEN> --initialise` on environment if not already and update `.env`
+## Directory Structure
 
+```
+cms/contentful/queries/
+├── index.ts                    # Barrel export file (manual updates required)
+├── fragments.ts                # Shared GraphQL fragments
+├── *.query.ts                  # Individual component queries
+└── README.md                   # This file
+```
 
-## Helpful Docs
+## How Queries Are Exported
 
-- [Contentful Migration](https://github.com/contentful/contentful-migration)
-- [Contentful Migration Reference Docs](https://github.com/contentful/contentful-migration/blob/main/README.md#reference-documentation)
-- [Contentful Data Model](https://www.contentful.com/developers/docs/concepts/data-model/)
+The query export system in this project is **semi-automatic**:
 
-### Instructions
+### The Process
 
-- Create your migration file in the scripts folder with the following format: `0002-description.cjs`
-- Write your migrations
-  - This should be with an up and a down function
-  - The up function updates the model
-  - The down function reversts your changes
-- Run your migration on a test environment with the following command: `pnpm exec contentful-cli-migrations --environment-id <your-env-name> --space-id <space-id> --management-token <CMA-TOKEN>`
-  - Optional Flags:
-    - `--rollback`: Rolls back one migration.
+1. **Individual Query Files** - Queries are defined in individual files with the pattern `*.query.ts`
+   - Example: `accordion.query.ts`, `carousel.query.ts`
 
-### Gotchas
+2. **Manual Barrel Export** - Queries are re-exported through `index.ts`
+   - Uses wildcard exports: `export * from './accordion.query.js'`
+   - **Note:** Exports use `.js` extensions even though source files are `.ts` (ESM compatibility)
 
-- Currently the rollback may change the version counter even if the migration doesnt run.
-  - for this just update the counter to the correct counter in contentful and rerun.
-- The migration may run and create a content type even if the whole migration doesnt run correctly.
-  - To fix you will need to delete the content type and re-run
+3. **Package-Level Export** - The barrel export is exposed via `package.json`:
+   ```json
+   "./cms/contentful/graphql": {
+     "import": "./dist/cms/contentful/queries/index.js",
+     "types": "./dist/cms/contentful/queries/index.d.ts"
+   }
+   ```
 
-### TODO
+## Creating a New Query
 
-- Fix rollback versioning
-  - This flag should cause a rollback to that specific version, in this case 0001 `--version 0001`
-  - It should be used with `--rollback`
-  - It should update dthe versionTracker entry on successful rollback
-- Run migration error handling
-  - runMigration is currently not working as expected and bumping the counter when the migration was aborted
+### Steps Required
+
+1. **Create Query File** - Add your query file: `yourComponent.query.ts`
+
+2. **Define Query** - Follow the established pattern:
+   ```typescript
+   import { gql } from 'graphql-tag'
+   import type { DocumentNode } from 'graphql'
+   import { someFragment } from './fragments.js' // If needed
+
+   export const getYourComponent: DocumentNode = gql`
+     ${someFragment}  // Include fragments if needed
+     query yourComponentQuery($id: String!, $preview: Boolean = false) {
+       yourComponent(id: $id, preview: $preview) {
+         __typename
+         # Add your fields here
+       }
+     }
+   `
+   ```
+
+3. **Update Barrel Export** - **MANUALLY ADD** export to `index.ts`:
+   ```typescript
+   export * from './yourComponent.query.js'
+   ```
+   - Maintain alphabetical order for consistency
+   - Use `.js` extension (not `.ts`)
+
+### Query Naming Conventions
+
+- **File Name:** `componentName.query.ts` (camelCase)
+- **Export Name:** `getComponentName` (camelCase with `get` prefix)
+- **Query Name:** `componentNameQuery` (camelCase with `Query` suffix)
+
+### Example
+
+```typescript
+// accordion.query.ts
+import { gql } from 'graphql-tag'
+import type { DocumentNode } from 'graphql'
+import { accordionItemFragment } from './fragments.js'
+
+export const getAccordion: DocumentNode = gql`
+  ${accordionItemFragment}
+  query accordionQuery($id: String!, $preview: Boolean = false) {
+    accordion(id: $id, preview: $preview) {
+      __typename
+      headline
+      accordionType
+      loadMoreButtonTitle
+      startOpen
+      accordionItemCollection {
+        items {
+          ...accordionItemFragment
+        }
+      }
+    }
+  }
+`
+```
+
+## Using Queries in Consumer Projects
+
+Queries are consumed via the package export:
+
+```typescript
+import { getAccordion, getCarousel } from '@cooperco/cooper-component-library/cms/contentful/graphql'
+```
+
+## Important Notes
+
+- **Manual Export Required:** The system is NOT fully automatic - you MUST manually update `index.ts` when adding new queries
+- **ESM Extensions:** Always use `.js` extensions in exports (even for `.ts` source files)
+- **Preview Mode:** All queries support a `preview` parameter for Contentful preview API
+- **Fragments:** Shared fragments are defined in `fragments.ts` and can be reused across queries

package/dist/cms/contentful/queries/README.md

@@ -0,0 +1,112 @@
+# GraphQL Queries
+
+This directory contains GraphQL queries for fetching content from Contentful CMS.
+
+## Directory Structure
+
+```
+cms/contentful/queries/
+├── index.ts                    # Barrel export file (manual updates required)
+├── fragments.ts                # Shared GraphQL fragments
+├── *.query.ts                  # Individual component queries
+└── README.md                   # This file
+```
+
+## How Queries Are Exported
+
+The query export system in this project is **semi-automatic**:
+
+### The Process
+
+1. **Individual Query Files** - Queries are defined in individual files with the pattern `*.query.ts`
+   - Example: `accordion.query.ts`, `carousel.query.ts`
+
+2. **Manual Barrel Export** - Queries are re-exported through `index.ts`
+   - Uses wildcard exports: `export * from './accordion.query.js'`
+   - **Note:** Exports use `.js` extensions even though source files are `.ts` (ESM compatibility)
+
+3. **Package-Level Export** - The barrel export is exposed via `package.json`:
+   ```json
+   "./cms/contentful/graphql": {
+     "import": "./dist/cms/contentful/queries/index.js",
+     "types": "./dist/cms/contentful/queries/index.d.ts"
+   }
+   ```
+
+## Creating a New Query
+
+### Steps Required
+
+1. **Create Query File** - Add your query file: `yourComponent.query.ts`
+
+2. **Define Query** - Follow the established pattern:
+   ```typescript
+   import { gql } from 'graphql-tag'
+   import type { DocumentNode } from 'graphql'
+   import { someFragment } from './fragments.js' // If needed
+
+   export const getYourComponent: DocumentNode = gql`
+     ${someFragment}  // Include fragments if needed
+     query yourComponentQuery($id: String!, $preview: Boolean = false) {
+       yourComponent(id: $id, preview: $preview) {
+         __typename
+         # Add your fields here
+       }
+     }
+   `
+   ```
+
+3. **Update Barrel Export** - **MANUALLY ADD** export to `index.ts`:
+   ```typescript
+   export * from './yourComponent.query.js'
+   ```
+   - Maintain alphabetical order for consistency
+   - Use `.js` extension (not `.ts`)
+
+### Query Naming Conventions
+
+- **File Name:** `componentName.query.ts` (camelCase)
+- **Export Name:** `getComponentName` (camelCase with `get` prefix)
+- **Query Name:** `componentNameQuery` (camelCase with `Query` suffix)
+
+### Example
+
+```typescript
+// accordion.query.ts
+import { gql } from 'graphql-tag'
+import type { DocumentNode } from 'graphql'
+import { accordionItemFragment } from './fragments.js'
+
+export const getAccordion: DocumentNode = gql`
+  ${accordionItemFragment}
+  query accordionQuery($id: String!, $preview: Boolean = false) {
+    accordion(id: $id, preview: $preview) {
+      __typename
+      headline
+      accordionType
+      loadMoreButtonTitle
+      startOpen
+      accordionItemCollection {
+        items {
+          ...accordionItemFragment
+        }
+      }
+    }
+  }
+`
+```
+
+## Using Queries in Consumer Projects
+
+Queries are consumed via the package export:
+
+```typescript
+import { getAccordion, getCarousel } from '@cooperco/cooper-component-library/cms/contentful/graphql'
+```
+
+## Important Notes
+
+- **Manual Export Required:** The system is NOT fully automatic - you MUST manually update `index.ts` when adding new queries
+- **ESM Extensions:** Always use `.js` extensions in exports (even for `.ts` source files)
+- **Preview Mode:** All queries support a `preview` parameter for Contentful preview API
+- **Fragments:** Shared fragments are defined in `fragments.ts` and can be reused across queries

package/dist/cms/queries/README.md

@@ -0,0 +1,112 @@
+# GraphQL Queries
+
+This directory contains GraphQL queries for fetching content from Contentful CMS.
+
+## Directory Structure
+
+```
+cms/contentful/queries/
+├── index.ts                    # Barrel export file (manual updates required)
+├── fragments.ts                # Shared GraphQL fragments
+├── *.query.ts                  # Individual component queries
+└── README.md                   # This file
+```
+
+## How Queries Are Exported
+
+The query export system in this project is **semi-automatic**:
+
+### The Process
+
+1. **Individual Query Files** - Queries are defined in individual files with the pattern `*.query.ts`
+   - Example: `accordion.query.ts`, `carousel.query.ts`
+
+2. **Manual Barrel Export** - Queries are re-exported through `index.ts`
+   - Uses wildcard exports: `export * from './accordion.query.js'`
+   - **Note:** Exports use `.js` extensions even though source files are `.ts` (ESM compatibility)
+
+3. **Package-Level Export** - The barrel export is exposed via `package.json`:
+   ```json
+   "./cms/contentful/graphql": {
+     "import": "./dist/cms/contentful/queries/index.js",
+     "types": "./dist/cms/contentful/queries/index.d.ts"
+   }
+   ```
+
+## Creating a New Query
+
+### Steps Required
+
+1. **Create Query File** - Add your query file: `yourComponent.query.ts`
+
+2. **Define Query** - Follow the established pattern:
+   ```typescript
+   import { gql } from 'graphql-tag'
+   import type { DocumentNode } from 'graphql'
+   import { someFragment } from './fragments.js' // If needed
+
+   export const getYourComponent: DocumentNode = gql`
+     ${someFragment}  // Include fragments if needed
+     query yourComponentQuery($id: String!, $preview: Boolean = false) {
+       yourComponent(id: $id, preview: $preview) {
+         __typename
+         # Add your fields here
+       }
+     }
+   `
+   ```
+
+3. **Update Barrel Export** - **MANUALLY ADD** export to `index.ts`:
+   ```typescript
+   export * from './yourComponent.query.js'
+   ```
+   - Maintain alphabetical order for consistency
+   - Use `.js` extension (not `.ts`)
+
+### Query Naming Conventions
+
+- **File Name:** `componentName.query.ts` (camelCase)
+- **Export Name:** `getComponentName` (camelCase with `get` prefix)
+- **Query Name:** `componentNameQuery` (camelCase with `Query` suffix)
+
+### Example
+
+```typescript
+// accordion.query.ts
+import { gql } from 'graphql-tag'
+import type { DocumentNode } from 'graphql'
+import { accordionItemFragment } from './fragments.js'
+
+export const getAccordion: DocumentNode = gql`
+  ${accordionItemFragment}
+  query accordionQuery($id: String!, $preview: Boolean = false) {
+    accordion(id: $id, preview: $preview) {
+      __typename
+      headline
+      accordionType
+      loadMoreButtonTitle
+      startOpen
+      accordionItemCollection {
+        items {
+          ...accordionItemFragment
+        }
+      }
+    }
+  }
+`
+```
+
+## Using Queries in Consumer Projects
+
+Queries are consumed via the package export:
+
+```typescript
+import { getAccordion, getCarousel } from '@cooperco/cooper-component-library/cms/contentful/graphql'
+```
+
+## Important Notes
+
+- **Manual Export Required:** The system is NOT fully automatic - you MUST manually update `index.ts` when adding new queries
+- **ESM Extensions:** Always use `.js` extensions in exports (even for `.ts` source files)
+- **Preview Mode:** All queries support a `preview` parameter for Contentful preview API
+- **Fragments:** Shared fragments are defined in `fragments.ts` and can be reused across queries