#130 US-YW6: Import Items from yWriter

[Anonymous]

Originally created by: smith-and-web
Originally owned by: smith-and-web

User Story

As a yWriter user,
I want to have my items database imported into Kindling,
So that important objects are tracked as references.

Parent Epic: [#123]

yWriter XML Structure

<ITEMS>
  <ITEM>
    <ID>1</ID>
    <Name>Grandmother's Jade Pendant</Name>
    <Desc>A small jade dragon on a gold chain. The pendant was given to Sarah's 
grandmother by her father before she left China. It contains a hidden compartment 
that Sarah doesn't know about.</Desc>
    <Aka>The Dragon Pendant; the jade necklace</Aka>
    <Tags>jewelry;heirloom;macguffin</Tags>
    <Image>items/pendant.jpg</Image>
  </ITEM>
</ITEMS>

Scene-Item Associations

Scenes reference items by ID:

<SCENE>
  <ID>1</ID>
  <Items>1;2</Items>  <!-- Semicolon-delimited item IDs -->
</SCENE>

Mapping Question

Open question: Should Items be:

1. A separate entity type in Kindling?
2. Merged with Locations as "World Elements"?
3. Stored as a special type of Character (with type: item)?

For now, recommend treating as separate entity type, similar to Characters and Locations.

Mapping to Kindling

yWriter Field	Kindling Field
<Name>	Item name
<Desc>	Description
<Aka>	Aliases (metadata)
<Tags>	Tags
<Image>	Image path (for future use)

Acceptance Criteria

• [ ] Imports all items from <ITEMS> section
• [ ] Maps Name field to item name
• [ ] Maps Desc field to item description
• [ ] Maps Aka field to item aliases/metadata
• [ ] Maps Tags field to item tags
• [ ] Creates item-scene associations based on <Items> IDs
• [ ] Items display in reference panel
• [ ] Items grouped appropriately (with locations? separately?)
• [ ] Handles missing/empty item fields gracefully

Edge Cases

• No items: Many yWriter projects don't use items
• Missing item: Scene references item ID that doesn't exist
• Duplicate names: Item named same as a location

[Anonymous]

Originally posted by: smith-and-web

Partial implementation in PR [#140]: Items are parsed from the yWriter file but not stored in Kindling since there's no Item model. This would require adding an Item entity to the data model. Keeping open for future implementation if needed.

[Anonymous]

• assigned_to: smith-and-web

[Anonymous]

Originally posted by: smith-and-web

Merged via https://github.com/smith-and-web/kindling/pull/162.

yWriter item import now maps:

• Name/Title + Desc (with markup conversion)
• Aka → reference attribute aliases
• Tags → reference attribute tags
• Image/ImageFile → reference attribute image

Includes unit test coverage for item field mapping.

[Anonymous]

Ticket changed by: smith-and-web

• status: open --> closed