sections.md

Sections

A section is a "partial recipe" which doesn't stand on its own. For example, you might have frosting as a section of a german chocolate cake recipe in your library. On the other hand, you might consider buttercream icing to be a recipe itself, only loosely associated with various other recipes.

This distinction is entirely in the mind of the cook, and varies contextually. Continuing the example, buttercream "becomes" a section of the cupcake recipe you're planning Clara's birthday party this weekend. When you're making the cupcakes, the icing is a section of the cupcakes recipe, even though they're separate in your library.

Entity Model

Sections are stored as recipes, with "section-ness" represented implicitly. Owned sections (frosting) are "part of" their owning recipe (german chocolate cake). Recipes (buttercream icing) may be by reference sections of other recipes (cupcakes). An owned section may also be the referent of by reference sections (reuse german chocolate cake's frosting for cupcakes, without 'promoting' frosting to a top-level recipe).

1. Add a new Recipe sectionOf; field to the Recipe class, backed by a ON DELETE RESTRICT FK column in the database.
   1. The value indicates the recipe the section is owned by.
   2. Null means the recipe is not an owned section.
2. Add a new boolean section; field to the IngredientRef class, for whether the ref is a section. Whether owned or by reference is not differentiated.
3. By reference sections are normal entity associations (aka today's subrecipes).
4. Owned sections are as if composed into their owning recipe.
   1. When an owned section is removed from a recipe, it is either:
      1. deleted if not otherwise referenced, or
      2. becomes owned by an arbitrary referrer.
   2. When a recipe is deleted, its owned sections are removed first.
5. An owned section can be promoted to a top-level recipe, which converts the section to be by reference.
6. A by reference section can be demoted to an owned section, as long as the referent is not already owned.

This model yields two different definitions of "section": a recipe owned by another (w/ sectionOf set), and a reference from one recipe to another (an IngredientRef referring to a Recipe). This mirrors the two different contextual viewpoints in the cook's mind. It's also the reason for all the italics.

GraphQL Schema

1. Sections (owned or by reference) are recipes; they can always be retrieved via LibraryQuery.getRecipeByIdand bulkIngredients.

2. Owned sections will not be returned from LibraryQuery.recipes or .suggestRecipesToCook.

3. Create a LibrarySearch input type with LibraryQuery.recipes's params and accept that instead.

4. Add a new Section type, sharing id, name, direction, ingredients, and labels with Recipe, plus a sectionOf: ID.

5. Add a new sections: [Section!]! to Recipe.

6. Add a new LibraryQuery.sections field which also accepts LibrarySearch and only returns owned sections (as a new SectionConnection and friends).

7. Add a new SectionInfo input type, sharing id, name, direction, ingredients, and labels with IngredientInfo. Owned sections will always have the data fields populated, as well as id once persistent. By reference sections will only ever have id.

8. Add a new sections: [SectionInfo!] to IngredientInfo.

Library

Search

1. Exclude owned sections from search results.
2. Exclude owned sections from recommendations.

Recipe Display

1. Owned sections participate in scaling, while by reference sections do not.
2. Sections with non-blank description float to the top w/ collapse as subrecipes do today.
3. Sections with no description fall to the bottom of the ingredient list, title as subheading.

Recipe Form

1. New "Add Section" button, to either:
   1. create a blank owned section, or
   2. search for owned sections to include by reference.
      1. This needs a toggle to search for recipes, instead of owned sections. Or between owned sections and everything?
2. Owned sections contain title, ingredients, directions, and labels.
   1. Title is required and gets defaulted to "MOAR Goober Whosit" or something.
   2. Ingredients are optional, with a blank ElEdit row visible to start.
      1. Cannot have owned subsections, but can have by reference subsections.
   3. Directions and labels are optional, and should start collapsed if empty (with an icon to toggle visibility).
3. By reference sections:
   1. are read only,
   2. show a link to their top-level recipe, which is the section itself if not owned, and
   3. can be one-click-replaced by a new owned section of the current recipe, duplicating the underlying recipe, as long as it doesn't have owned sections.
4. Adding a recipe as an ingredient creates a by reference section (as today).
   1. Recog suggestions (for ElEdit) exclude sections (like search results).
5. Non-section ingredients can be dragged between owned sections and/or the top-level recipe.
6. Sections can be reordered, separate from reordering their ingredients. On the form, they don't float/fall.
7. Sections can be removed from the recipe.
8. Owned sections have a "Used By" button, if any other recipe includes them by reference, which opens a dialog to enumerate referrers. Should all sections?

Textract

1. FUTURE: New "New Section" action button, which will create a new (name-defaulted) section and add the selected text as its ingredients.
2. FUTURE: make the existing buttons into combo buttons which allow targeting a section, instead of the top-level recipe, if any sections exist.

Cook This!

FUTURE

Planner

Owned sections shouldn't have a "Cook" button.

Cook Planned Recipe or Bucket

1. Remove ingredient scaling UI; it's too late.
2. Sections with non-blank description float to the top w/ collapse as subrecipes do today.
3. Sections with no description fall to the bottom of the ingredient list, title as subheading.
4. Hide "I Cooked It!" and "Open Library Recipe" for
   1. owned sections if the top-level recipe is also visible, and
   2. all sections without a description.

Shopping

No special handling.

FUTURE: Adjust the attribution breadcrumbs, so section names come after the top-level recipe? Using sugar for the baking example:

• sugar (10 c)
  • 1 c sugar
    German Chocolate Cake / Our Week
  • 2 c sugar
    Buttercream Icing / Cupcakes / Clara's Birthday / Our Week
  • 3 c sugar
    Cupcakes / Clara's Birthday / Our Week
  • 4 c sugar
    Frosting / German Chocolate Cake / Our Week

I believe the frosting attribution would be better as "German Chocolate Cake - Frosting / Our Week". This gets awkward with Clara's cupcakes, as the same rule would yield "Cupcakes - Buttercream Icing / Clara's Birthday / Our Week" for the icing (reasonable) and "Clara's Birthday - Cupcakes / Our Week" for the cupcakes themselves (less reasonable). This might need to pass section ownership information from library to planner, so only frosting gets flipped around. Or maybe everything should always be top-down, period?

Note that the "Our Week" breadcrumb is only visible if you're shopping multiple plans, and "Clara's Birthday" might be a bucket, not a plan item.

Plan Sidebar (and Calendar)

1. ASSUMPTION: Sections usually stay with their recipe, so if you want to move them, having to open the full planner is reasonable for the reduced clutter of the sidebar. Hide planned recipes which:
   1. are a section,
   2. are a descendant of their aggregate, and
   3. are in the same bucket as their aggregate, or not bucketed.

Pantry Item Admin

1. The "Uses" popup needs to include the top-level recipe's name for owned sections.
   1. Include "and 7 other referrers"?
   2. For by reference sections too?

Discussion

1. A quantity of an owned section makes no sense; it's part of this recipe.
2. A quantity of a by reference section makes a lot of sense.
   1. If you want to add buttercream icing to a recipe, you'd want to multiply across the buttercream recipe's yield. E.g., if buttercream yields 4 c icing, but I only need 2 c for my recipe, I want "1/2 buttercream icing"
3. A quantity of a by reference section targeting an owned section is ... uh
   1. If you want to reuse german chocolate cake's coconut frosting for cupcakes, there's no yield for the frosting alone. If the cake recipe makes two 9-inch layers, but your cupcake recipe makes 12, you need a lot less frosting... but there's no yield on a section to multiple across.