Section Header Component

A flexible Vue 3 + Quasar component for displaying section headers with customizable labels, typography, and slot-based content. Perfect for creating consistent section headers throughout your application.

Features

• ✅ Quasar Integration - Built with Quasar components (QItem, QItemSection)
• ✅ TypeScript Ready - Full TypeScript support
• ✅ Customizable - Control label, colors, typography, and layout
• ✅ Slot Support - Add custom content via default slot
• ✅ Flexible Layout - Side or inline slot positioning
• ✅ Responsive - Works on all screen sizes

Installation

npm install itc-section-header
# or
pnpm install itc-section-header

Requirements

• Vue 3.x
• Quasar 2.x

These are peer dependencies and must be installed in your project.

Usage

Basic Example

<script setup>
import { SectionHeader } from 'itc-section-header'
</script>

<template>
  <SectionHeader label="My Section Title">
    <q-btn label="Action" color="primary" />
  </SectionHeader>
</template>

With Custom Styling

<template>
  <SectionHeader
    label="Settings"
    label-color="text-primary"
    label-typography="text-h6"
    label-center
  >
    <q-btn icon="settings" color="primary" />
  </SectionHeader>
</template>

Without Label

<template>
  <SectionHeader :show-label="false">
    <q-btn-group>
      <q-btn label="Add" color="positive" />
      <q-btn label="Edit" color="primary" />
      <q-btn label="Delete" color="negative" />
    </q-btn-group>
  </SectionHeader>
</template>

Inline Slot Content

<template>
  <SectionHeader
    label="Content Section"
    :show-slot-as-side="false"
  >
    <div class="row q-gutter-sm">
      <q-chip label="Tag 1" />
      <q-chip label="Tag 2" />
    </div>
  </SectionHeader>
</template>

In List Context

<template>
  <q-list>
    <SectionHeader label="Section 1" />
    <q-item>Item 1</q-item>
    <q-item>Item 2</q-item>
    
    <SectionHeader label="Section 2" />
    <q-item>Item 3</q-item>
    <q-item>Item 4</q-item>
  </q-list>
</template>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | label | String | '' | Label text to display | | labelColor | String | 'text-dark' | CSS class for label color | | labelTypography | String | 'text-body1' | CSS class for label typography (e.g., 'text-h6', 'text-h5') | | labelCenter | Boolean | false | Center align the label | | showLabel | Boolean | true | Show/hide the label | | showSlotAsSide | Boolean | true | Show slot content on the side (true) or inline (false) | | mainPadding | String | 'q-px-sm' | Main padding class (Quasar padding classes) |

Examples

Different Typography

<template>
  <!-- Large header -->
  <SectionHeader
    label="Main Section"
    label-typography="text-h5"
    label-color="text-primary"
  />

  <!-- Medium header -->
  <SectionHeader
    label="Sub Section"
    label-typography="text-h6"
  />

  <!-- Small header -->
  <SectionHeader
    label="Minor Section"
    label-typography="text-body2"
  />
</template>

With Actions

<template>
  <SectionHeader label="User Management">
    <q-btn-group>
      <q-btn
        icon="add"
        label="Add User"
        color="positive"
        size="sm"
      />
      <q-btn
        icon="refresh"
        label="Refresh"
        color="primary"
        size="sm"
      />
    </q-btn-group>
  </SectionHeader>
</template>

Custom Padding

<template>
  <SectionHeader
    label="Custom Padding"
    main-padding="q-pa-md"
  >
    <q-btn label="Action" />
  </SectionHeader>
</template>

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues or questions, please visit: GitHub Issues

Development

Path Aliases

This template supports importing files using the src/ prefix without relative paths:

// ✅ Good - Using path alias
import { DEFAULT_LABEL_COLOR } from "src/consts";
import SectionHeader from "src/components/SectionHeader.vue";

// ❌ Avoid - Relative paths (still works, but not recommended)
import { DEFAULT_LABEL_COLOR } from "../consts";
import SectionHeader from "./components/SectionHeader.vue";

Project Structure

├─ src/
│   ├─ components/          # Vue components
│   │   └─ SectionHeader.vue
│   ├─ consts.ts           # Constants
│   ├─ index.ts            # Main export file
│   └─ vue-shim.d.ts       # Vue type declarations
├─ dist/                   # Build output (generated)
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

Building

Build for Production

pnpm run build
# or
npm run build

This will:

• Compile TypeScript to JavaScript
• Bundle Vue components
• Generate both ES Modules (.js) and CommonJS (.cjs) formats
• Output to dist/ directory with preserved src/ structure

Build Output Structure

dist/
└─ src/
   ├─ index.js              # ES Module entry
   ├─ index.cjs             # CommonJS entry
   ├─ components/
   │   └─ ...
   └─ ...

Testing Locally

Option 1: Using pnpm link (Recommended)

1. In your plugin directory:

   pnpm link --global

2. In your test project:

   pnpm link --global itc-section-header

3. Use in your project:

   <script setup>
   import { SectionHeader } from "itc-section-header";
   </script>

Option 2: Using File Path

1. In your test project's package.json:

   {
     "dependencies": {
       "itc-section-header": "file:../path/to/quasar-package-starter-kit-plugins-section-header"
     }
   }

2. Install:

   pnpm install

3. Use in your project:

   <script setup>
   import { SectionHeader } from "itc-section-header";
   </script>

Development Workflow

For active development with auto-rebuild:

Run in watch mode:

pnpm run dev

Changes will rebuild automatically. Restart your test project's dev server to pick up changes.

Publishing to npm

Before Publishing

1. Update package.json:

   • Set correct name (must be unique on npm)
   • Update version (follow semver)
   • Add description, keywords, author, license
   • Verify files array includes only what should be published:

     {
       "files": ["dist", "README.md"]
     }

2. Build the package:

   pnpm run build

3. Test the build locally (see Testing Locally section above)

Publishing Steps

1. Login to npm:

   npm login

2. Verify you're logged in:

   npm whoami

3. Check what will be published:

   npm pack --dry-run

4. Publish:

   npm publish

5. Verify on npm: Visit https://www.npmjs.com/package/itc-section-header

Version Management

Use npm version commands to bump versions:

# Patch version (1.0.0 → 1.0.1)
npm version patch

# Minor version (1.0.0 → 1.1.0)
npm version minor

# Major version (1.0.0 → 2.0.0)
npm version major

Then publish:

npm publish

Configuration

External Dependencies

By default, vue and quasar are marked as external (not bundled). To add more:

Update vite.config.ts:

rollupOptions: {
  external: (id) => {
    return (
      id === "vue" ||
      id === "quasar" ||
      id.startsWith("@quasar/") ||
      id.startsWith("quasar/") ||
      id === "some-other-package"
    ); // Add here
  };
}

Build Formats

The template builds both ES Modules and CommonJS. To change formats:

Update vite.config.ts:

build: {
  lib: {
    formats: ["es", "cjs"]; // or ['es'], ['cjs'], etc.
  }
}

Troubleshooting

TypeScript Errors

• "Cannot find module 'src/...'": Restart TypeScript server
• "Cannot find module 'path'": Ensure @types/node is installed
• Path aliases not working: Check both tsconfig.json and vite.config.ts have matching aliases

Build Errors

• "Rollup failed to resolve import": Add the package to external in vite.config.ts
• "Preprocessor dependency not found": Install required preprocessors (e.g., sass-embedded for SCSS)

Import Errors in Test Project

• Ensure the package is built (pnpm run build)
• Check package.json exports are correct
• Verify the import path matches your exports

Happy coding! 🚀