pkg_filename_composer

A small, framework‑agnostic library to compose file names from ordered parts. It ships the core model (this package) and can be used by Flutter or other UI layers to build editors and widgets.

Consistent file names make automation and searching much easier. Instead of hand‑crafting strings across your app, use a single, test‑covered model that:

• keeps an ordered list of parts (prefix, sizes, sequence, etc.)
• toggles which parts are active
• supports insertion/removal/reordering
• serializes to/from JSON and strings
• merges two configurations safely

Core concepts

• Part type: enum HHFilenameComposerPartType defines all parts that can appear in a filename. Each value exposes canEdit and canRemove flags.
• Part data: HHFilenameComposerPartData couples a part type with its data (string) and active state.
• Seed: HHFilenameComposerSeed provides initial data values (e.g. sheet size, sides). It has defaultSeed and zeroSeed helpers.
• Composer: HHFilenameComposer is the stateful model which holds a list of HHFilenameComposerPartData and produces the final filename.

The default active parts are defined by HHFilenameComposer.defaultActive and include the non‑removable parts such as prefix_hard, sheet_size, sides, page_size, common_marker, sequence, duplication.

Quick start

import 'package:pkg_filename_composer/pkg_filename_composer.dart';

void main() {
  // Start with default active parts and empty data
  final composer = HHFilenameComposer();

  // Provide data for some parts (you can also supply a Seed at construction time)
  composer.setItemData(
    composer.getItemData(HHFilenameComposerPartType.prefix_hard).copyWith(data: 'IMPO'),
  );
  composer.setItemData(
    composer.getItemData(HHFilenameComposerPartType.sheet_size).copyWith(data: '210x297'),
  );
  composer.setItemData(
    composer.getItemData(HHFilenameComposerPartType.sides).copyWith(data: 'DZ'),
  );
  composer.setItemData(
    composer.getItemData(HHFilenameComposerPartType.page_size).copyWith(data: '80x60'),
  );
  composer.setItemData(
    composer.getItemData(HHFilenameComposerPartType.sequence).copyWith(data: '001'),
  );
  composer.setItemData(
    composer.getItemData(HHFilenameComposerPartType.duplication).copyWith(data: '1x printen'),
  );

  final filename = composer.getFilename(extension: 'pdf');
  print(filename); // e.g. IMPO_210x297_DZ_80x60_001_1x printen.pdf
}

Using a seed

final seed = HHFilenameComposerSeed(
  prefix_hard: 'IMPO',
  sheet_size: '210x297',
  sides: 'DZ',
  page_size: '80x60',
  common_marker: 'Algemeen pakket',
  sequence: '001',
  duplication: '1x printen',
);

final composer = HHFilenameComposer(seed: seed);
final name = composer.getFilename();

Add, remove, reorder parts

final composer = HHFilenameComposer(seed: HHFilenameComposerSeed.zeroSeed);

// Activate an optional part
composer.addItem(HHFilenameComposerPartType.prefix);
composer.setItemData(
  composer.getItemData(HHFilenameComposerPartType.prefix).copyWith(data: 'STACK'),
);

// Remove a part (only if canRemove is true for that part type)
composer.removeItem(HHFilenameComposerPartType.prefix);

// Reorder by index
composer.reorderItem(0, 2);

// Or swap by item
final item = composer.getItemData(HHFilenameComposerPartType.page_size);
composer.swapItem(item, 1);

Serialization

• To JSON object:

final json = composer.toJson();

• To JSON string:

final jsonString = composer.stringify();

• From JSON map/string:

final composer1 = HHFilenameComposer.fromJson(json);
final composer2 = HHFilenameComposer.fromString(jsonString);

• Merge two configurations (active state and data are merged):

final target = HHFilenameComposer();
final other = HHFilenameComposer.fromJson(json);

target.merge(other);

JSON format

A minimal example of the serialized structure (pretty‑printed for readability):

{
  "data": [
    { "partType": "prefix_hard", "data": "IMPO", "active": true },
    { "partType": "sheet_size",  "data": "210x297", "active": true },
    { "partType": "sides",       "data": "DZ", "active": true },
    { "partType": "page_size",   "data": "80x60", "active": true },
    { "partType": "common_marker","data": "Algemeen pakket", "active": true },
    { "partType": "sequence",    "data": "001", "active": true },
    { "partType": "duplication", "data": "1x printen", "active": true }
  ]
}

Note: The enum value document_subject used to be named subject. The deserializer keeps backward compatibility for old data.

API surface (high‑level)

• HHFilenameComposer
  • constructors: HHFilenameComposer({seed, defaultActive}), fromJson(...), fromJsonObject(...), fromString(...)
  • getters: selectedPartTypes, unselectedPartTypes
  • mutators: addItem(partType), removeItem(partType), reorderItem(oldIndex, newIndex), swapItem(item, targetIndex), setItemData(data), merge(other), clear()
  • output: getFilename({values, extension, defaultValue}), toJson(), stringify()
• HHFilenameComposerSeed
  • fields for every part type, plus presets: defaultSeed, zeroSeed
  • helpers: fromPartData(...), merge(...), set(...), toJson(), etc.
• HHFilenameComposerPartType
  • enum with canEdit and canRemove flags
• HHFilenameComposerPartData
  • value object with partType, data, active and helpers like copyWith, fromJson, toJson

Consult the source files in lib/src/common/... for full details.

Testing

Run the package tests:

dart test

The test suite includes end‑to‑end examples of composing, (de)serializing and merging.

License

See the LICENSE file. Copyright © HuigHaverlag BV.

Changelog

0.0.3 - 2025-11-21

Changed

• Version bump from 0.0.2 to 0.0.3 (test -> 1.28.0 (was 1.27.0)).

0.0.2 - 2025-11-11

Changed

• Version bump from 0.0.1 to 0.0.2 (test -> 1.27.0 (was 1.26.3)).

0.0.1 - 2025-10-19

• Initial version.